Crear Facturación

Permite registrar uno o múltiples productos facturados en el sistema mediante una única petición. Cada registro relaciona un producto de un pedido con la factura emitida por el ERP e indica la cantidad y el factor facturados, el valor facturado y la fecha de la factura. Este endpoint está diseñado para operaciones en lote (batch), permitiendo insertar hasta 10,000 registros por petición.

Método: POST

Endpoint

https://api.ventasremotas.com/v1/invoicing/batch-create

Nota

Es necesario el envío del token de acceso Subscription-Key para hacer uso de este endpoint. Para ver cómo generar el token, vea Activación Suscripción a RSales API.

Encabezados de la solicitud

Header	Valor	Descripción
Content-Type	application/json	Indica que los datos se envían en formato JSON
Accept	application/json	Indica que la respuesta debe estar en formato JSON
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token

---

Parámetros del Cuerpo (Body)

El body debe ser un array de objetos, donde cada objeto representa un producto facturado a crear.

Límites

Parámetro	Valor	Descripción
Mínimo de items	1	El array no puede estar vacío
Máximo de items	10,000	Número máximo de productos facturados por petición

Campos

El cuerpo (Body) de la solicitud debe enviarse en formato JSON y debe incluir un array con los siguientes parámetros.

Importante

Todos los campos requeridos deben estar presentes en cada objeto del array, incluso los campos que admiten nulo (Nulo: Sí). Si un campo no aplica para un registro, envíelo con valor null. Los campos marcados como Opcional pueden omitirse por completo; si se omiten, se guarda su valor por defecto.

Clave de identificación

Un producto facturado se identifica de forma única por la combinación de document_number + document_type + product_code + item_number + client_id. Si ya existe un registro con esa combinación, será ignorado (no se duplicará).

Campo	Tipo	Nulo	Restricciones	Descripción
client_id	string (max 18)	No	No permite: espacio, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Código del cliente al que se facturó
seller_id	string (max 18)	No	No permite: espacio, #, %, &, *, {`, `}, \, :, <, >, ?, /, +, .	Código del vendedor asociado al pedido facturado
order_code	string (max 30)	No	Opcional	Código del pedido al que pertenece el producto facturado. Si se omite, se guarda vacío (""). No admite null
item_number	int	No	Mínimo: 1, Máximo: 999	Orden en que se facturó el producto
document_type	string (max 50)	No		Tipo de documento de la factura (ej: “FACTURA”)
document_number	string (max 20)	No		Número de la factura emitida por el ERP
invoice_date	datetime	No	Formato: YYYY-MM-DD HH:MM:SS	Fecha de emisión de la factura
product_code	string (max 20)	No	No permite: espacio, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Código del producto facturado
quantity	decimal (18, 2)	No		Cantidad facturada del producto
factor	decimal (18, 0)	No	Sin decimales	Factor (unidad de empaque) facturado
price	decimal (18, 2)	Sí		Precio unitario del producto en la factura
tax	decimal (18, 2)	Sí		Impuesto aplicado al producto en la factura
charges	decimal (18, 2)	Sí		Cargos en valor del producto (usualmente el impoconsumo)
discount	decimal (18, 2)	Sí		Descuento aplicado al producto facturado
total	decimal (18, 2)	No		Valor total facturado del producto

Formato de tipos de dato

• string (max N): Cadena de texto con longitud máxima de N caracteres.
• int: Número entero dentro del rango indicado en las restricciones.
• decimal (p, s): Número decimal donde p es la precisión total (dígitos enteros + decimales) y s es la escala (dígitos decimales).
  • Ejemplo: decimal (18, 2) permite hasta 16 dígitos enteros y 2 decimales (ej: 9999999999999999.99)
  • Ejemplo: decimal (18, 0) permite hasta 18 dígitos enteros y ningún decimal (ej: 6)
• datetime: Fecha y hora en formato YYYY-MM-DD HH:MM:SS (ej: 2024-06-15 10:30:00).

---

Ejemplo de Solicitud

Aquí tienes un ejemplo de cómo debería quedar el cuerpo de la solicitud en formato JSON:

[
  {
    "client_id": "CLI-001",
    "seller_id": "VEN-010",
    "order_code": "PED-2024-000875",
    "item_number": 1,
    "document_type": "FACTURA",
    "document_number": "FV-2024-001520",
    "invoice_date": "2024-06-15 00:00:00",
    "product_code": "PROD-0001",
    "quantity": 12,
    "factor": 6,
    "price": 18500.0,
    "tax": 19.0,
    "charges": 0.0,
    "discount": 5.0,
    "total": 1261440.0
  },
  {
    "client_id": "CLI-001",
    "seller_id": "VEN-010",
    "order_code": "PED-2024-000875",
    "item_number": 2,
    "document_type": "FACTURA",
    "document_number": "FV-2024-001520",
    "invoice_date": "2024-06-15 00:00:00",
    "product_code": "PROD-0042",
    "quantity": 3.5,
    "factor": 1,
    "price": 42000.0,
    "tax": 19.0,
    "charges": null,
    "discount": null,
    "total": 174930.0
  }
]

---

Ejemplo de Respuesta

201 - OK

{
    "statusCode": 201,
    "message": "Invoicing created successfully"
}

Importante

Los productos facturados que ya existan en el sistema (misma combinación de document_number + document_type + product_code + item_number + client_id) serán ignoradas sin generar error, al igual que los productos cuyo client_id o seller_id no exista en la empresa. Solo se insertarán los registros nuevos con referencias válidas.

Status 400

{
    "statusCode": 400,
    "errors": [
        {
            "message": "Invalid JSON in request body"
        }
    ]
}

Status 415

{
    "statusCode": 415,
    "errors": [
        {
            "message": "Content-Type: application/json is required"
        }
    ]
}

Status 422

Errores globales (estructura del body)

Si el body no es un array:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body must be an array"
        }
    ]
}

Si el array está vacío:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body cannot be empty"
        }
    ]
}

Si excede el límite de 10,000 items:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Array exceeds maximum limit of 10000 items"
        }
    ]
}

Errores por item (validación de campos)

Los errores se agrupan por el índice del item en el array:

{
    "statusCode": 422,
    "errors": [
        {
            "index": 0,
            "errors": [
                {
                    "field": "document_number",
                    "message": "Field is required"
                },
                {
                    "field": "quantity",
                    "message": "Field must be of type decimal"
                }
            ]
        },
        {
            "index": 2,
            "errors": [
                {
                    "field": "item_number",
                    "message": "Field must be greater than or equal to 1"
                }
            ]
        }
    ]
}

Tipos de Errores de Validación por Campo

Errores de presencia y nulidad:

Error	Descripción
Field is required	El campo no fue enviado en el objeto (la clave no existe)
Field cannot be null or empty	El campo fue enviado con valor null o vacío y no acepta nulos
Unknown field	Se envió un campo que no existe en la configuración
Item must be an object	Un elemento del array no es un objeto JSON

Errores de tipo de dato:

Error	Descripción
Field must be a string	El valor no es una cadena de texto
Field must be of type integer	El valor no es un número entero
Field must be a valid integer	El formato del entero es inválido
Field must be of type decimal	El valor no es un número decimal válido
Field must be a valid decimal (e.g., 1.5, 10.25)	El formato del decimal es inválido
Field must be a valid decimal number	El valor no es un número decimal válido (NaN, Infinity)
Field must be a valid datetime (YYYY-MM-DD HH:MM:SS)	El valor no es una fecha/hora válida

Errores de longitud, rango y precisión:

Error	Descripción
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida
Field must be greater than or equal to 1	item_number es menor al mínimo permitido
Field must be less than or equal to 999	item_number excede el máximo permitido
Field exceeds maximum of X integer digits (precision: P, scale: S)	El número excede los dígitos enteros permitidos
Field exceeds maximum of X decimal places	El número excede los decimales permitidos (factor no admite decimales)

Errores de formato:

Error	Descripción
Field contains forbidden characters. The following are not allowed: space, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Los campos client_id, seller_id o product_code contienen caracteres prohibidos

Status 423

{
    "statusCode": 423,
    "errors": [
        {
            "message": "Resource is locked and cannot be accessed."
        }
    ]
}

Recurso bloqueado

Este error ocurre cuando otra operación de creación o actualización de facturación con la misma Subscription-Key está en progreso. Espere a que la operación anterior finalice e intente nuevamente.

Status 500

Error de conexión a base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Error connecting to database"
        }
    ]
}

Error de operación en base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Database operation failed"
        }
    ]
}

Error en Redis

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Redis operation failed"
        }
    ]
}

Error en validaciones

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error in the validations"
        }
    ]
}

Error inesperado

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error"
        }
    ]
}

Error del Servidor

Estos errores indican problemas internos en el servidor, la base de datos o el servicio de cache. Si persisten, contacta al equipo de soporte.