Apariencia
Orden de entrega individual
POST /api/Invoice/add_list_delivery_independent
Emite órdenes (notas) de entrega independientes, es decir, que no dependen de una factura: envías el cliente, los productos y los datos del traslado (origen, destino, vehículo, chofer y despachador). Admite varias órdenes por solicitud; cada una recibe un número de control y se firma electrónicamente. Devuelve, por cada orden guardada, su número de control y el PDF.
Para una orden de entrega asociada a una factura ya emitida, usa Orden de entrega.
Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroSerie | string | Sí | Código de la serie de numeración del negocio (por ejemplo "A"). |
cantidadNE | integer | Sí | Cantidad de órdenes enviadas. Debe ser un entero e igual al número de elementos de notasDeEntregas. |
notasDeEntregas | array | Sí | Órdenes a emitir. Al menos una. Ver notasDeEntregas[]. |
notasDeEntregas[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroDeNotaDeEntrega | string | Sí | Número que tendrá la orden. Solo dígitos, máximo 19 caracteres. No puede repetirse dentro del envío ni existir ya en el negocio. |
documentoIdentidadCliente | string | Sí | RIF o cédula del cliente: letra V, E, P, J, G o C seguida de 8 a 10 dígitos, sin guiones. Ejemplo: J123456789. |
nombreRazonSocialCliente | string | Sí | Nombre o razón social del cliente. |
correoCliente | string | Sí | Correo del cliente. Se normaliza (minúsculas, sin espacios ni caracteres no permitidos) y debe quedar como un correo válido. |
direccionCliente | string | Sí | Dirección fiscal del cliente. |
telefonoCliente | string | Sí | Teléfono del cliente, por ejemplo "04141234567". |
origen | string | Sí | Lugar de origen del traslado. |
destino | string | Sí | Lugar de destino del traslado. |
productos | array | Sí | Productos que se entregan. Al menos uno. Ver productos[]. |
empleados | array | Sí | Debe incluir al menos un chofer y un despachador. Ver empleados[]. |
vehiculo | object | Sí | Datos del vehículo. Ver vehiculo. |
productos[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
codigoProducto | string | Sí | Código del producto, máximo 13 caracteres, sin espacios. No puede repetirse dentro de la misma orden. Si no existe en el negocio, el producto se crea. |
nombreProducto | string | Sí | Nombre del producto, máximo 70 caracteres. |
descripcionProducto | string | Sí | Descripción que se imprime en la línea, máximo 70 caracteres. |
tipoImpuesto | string | Sí | Alícuota de IVA: E (exento, 0 %), R (reducida, 8 %), G (general, 16 %), A (adicional, 31 %), P (percibido, 0 %). |
cantidadAdquirida | number o string | Sí | Cantidad mayor que 0, con punto decimal (por ejemplo 10 o "2.50"). Sin signo ni separadores de miles. |
precioProducto | string | Sí | Precio unitario sin IVA, mayor que 0, con hasta 2 decimales y separador . o , (por ejemplo "150.00" o "2,55"). Sin separadores de miles. |
empleados[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
nombre | string | Sí | Nombre del empleado. |
apellido | string | Sí | Apellido del empleado. |
DocumentoIdentidad | string | Sí | Letra V, E, P, J, G o C seguida de exactamente 8 dígitos. Ejemplo: V12345678. |
cargo | string | Sí | chofer o despachador (no distingue mayúsculas: Chofer también vale). |
correo | string | Sí | Correo electrónico válido. Identifica al empleado; si no existe, se registra como chofer o despachador del negocio. |
vehiculo
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
placaVehiculo | string | Sí | Placa del vehículo. |
tipoVehiculo | string | Sí | Tipo de vehículo. |
colorVehiculo | string | Sí | Color del vehículo. |
codigoVehiculo | string | Sí | Código interno del vehículo. |
Ejemplo de solicitud
json
{
"numeroSerie": "A",
"cantidadNE": 1,
"notasDeEntregas": [
{
"numeroDeNotaDeEntrega": "000101",
"documentoIdentidadCliente": "J123456789",
"nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
"correoCliente": "compras@example.com",
"direccionCliente": "Av. Principal, Edificio Ejemplo, Caracas",
"telefonoCliente": "04141234567",
"origen": "Almacén principal, Caracas",
"destino": "Sucursal Valencia",
"productos": [
{
"codigoProducto": "PROD-001",
"nombreProducto": "PRODUCTO A",
"descripcionProducto": "PRODUCTO A PRESENTACION 1 KG",
"tipoImpuesto": "G",
"cantidadAdquirida": "10.00",
"precioProducto": "150.00"
},
{
"codigoProducto": "PROD-002",
"nombreProducto": "PRODUCTO B",
"descripcionProducto": "PRODUCTO B EXENTO",
"tipoImpuesto": "E",
"cantidadAdquirida": "5",
"precioProducto": "80,00"
}
],
"empleados": [
{
"nombre": "Pedro",
"apellido": "Pérez",
"DocumentoIdentidad": "V12345678",
"cargo": "chofer",
"correo": "chofer@example.com"
},
{
"nombre": "Ana",
"apellido": "Gómez",
"DocumentoIdentidad": "V87654321",
"cargo": "despachador",
"correo": "despachador@example.com"
}
],
"vehiculo": {
"placaVehiculo": "AB123CD",
"tipoVehiculo": "CAMION",
"colorVehiculo": "BLANCO",
"codigoVehiculo": "CAM-001"
}
}
]
}Respuesta exitosa
HTTP 200
json
{
"success": true,
"message": "Notas de entrega guardadas satisfactoriamente",
"delivery_note_errors": [],
"delivery_note_success": [
{
"delivery_note_number": "000101",
"control_number": "00-00000129",
"delivery_note_pdf": "https://api.example.com/readonly/export_pdf/0e8b5f2a-7c3d-41e9-a6b2-d4f8c1e7a935"
}
]
}| Clave | Descripción |
|---|---|
success | true si se guardó al menos una orden. Si todas estaban registradas: false con HTTP 409. |
message | Notas de entrega guardadas satisfactoriamente, o Las notas de entrega se guardaron correctamente, pero algunas estaban duplicadas y no pudieron guardarse si alguna se rechazó. |
delivery_note_errors | Arreglo con los numeroDeNotaDeEntrega no guardados porque ya existían en el negocio o estaban repetidos en el envío. |
delivery_note_success | Una entrada por orden guardada: delivery_note_number, control_number (serie-########) y delivery_note_pdf. |
warning_control_numbers | Solo aparece cuando al negocio le quedan pocos números de control. |
Errores
Los errores devuelven "success": false con el código HTTP correspondiente (400 datos inválidos, 404 no encontrado, 409 conflicto, 500 error al guardar; ver Errores). Los errores de validación de campos se devuelven juntos en un solo message. En los mensajes, la orden se identifica por su numeroDeNotaDeEntrega.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Número de Serie es obligatorio. | Falta numeroSerie. |
| 400 | El campo Cantidad de Notas de Entrega es obligatorio. | Falta cantidadNE (si no es entero: El campo Cantidad de Notas de Entrega debe ser un número entero.). |
| 400 | El campo Notas de Entrega es obligatorio y no debe estar vacío. | Falta notasDeEntregas o está vacío. |
| 400 | La cantidad de productos por nota de entrega no puede ser mayor a 50 | Se superó el límite de productos por documento configurado en la plataforma (el número varía). La respuesta incluye notas_error con numeroDeNotaDeEntrega y cantidadProductos de cada orden excedida. |
| 400 | El Documento de Identidad del Cliente en la nota 000101 debe tener el formato correcto (letra V, E, P, J, G o C seguida de 8 a 10 dígitos). Ejemplo: V12345678 | Documento del cliente inválido. |
| 400 | El campo Correo del Cliente en la nota 000101 es inválido incluso después de limpieza. Valor recibido: ... | Correo del cliente inválido. |
| 400 | El campo Teléfono del Cliente en la nota 000101 es obligatorio. | Falta un dato del cliente o del traslado (análogos para Nombre o Razón Social, Correo, Dirección, Origen y Destino). |
| 400 | El campo Productos en la nota 000101 es obligatorio y no debe estar vacío. | Falta productos. |
| 400 | El campo Nombre del Producto en el producto 1 de la nota 000101 no puede exceder los 70 caracteres. | Dato de producto inválido (hay mensajes análogos para código, descripción, tipo de impuesto, cantidad y precio). |
| 400 | El campo Precio del Producto en el producto 1 de la nota 000101 debe ser un número decimal válido con punto o coma (sin caracteres especiales ni negativos). | Precio con más de 2 decimales o caracteres no válidos. |
| 400 | El campo Trabajador en la nota 000101 es obligatorio y no debe estar vacío. | Falta empleados. |
| 400 | El Documento de Identidad del Trabajador en la nota 000101 debe tener el formato correcto (letra V, E, P, J, G o C seguida de 8 dígitos). Ejemplo: V12345678 | Documento del empleado inválido. |
| 400 | El campo Vehículo en la nota 000101 es obligatorio y no debe estar vacío. | Falta vehiculo (si falta un dato: El campo Placa del Vehículo en la nota 000101 es obligatorio., etc.). |
| 400 | La nota de entrega 000101 necesita un Chofer y un Despachador. | Falta un chofer o un despachador. |
| 400 | Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, ... | El negocio no tiene configurado su tipo de contribuyente. |
| 401 / 400 | Ver Errores | Token ausente, mal formado, inválido o vencido. |
| 400 | Cantidad de notas de entrega incorrecta. | cantidadNE no coincide con el número de órdenes enviadas. |
| 400 | Error: Productos duplicados en la misma nota de entrega. | Un codigoProducto se repite dentro de la misma orden. |
| 409 | El comercio no posee más números de control activos. | Se agotaron los números de control durante el proceso. |
| 409 | No existe un número de control asociado al comercio. | El negocio no tiene números de control. |
| 404 | El comercio indicado aún no está registrado. | No se encontró el negocio del token. |
| 409 | Paquete incorrecto | Al registrar un chofer o despachador nuevo se superó el límite de usuarios del plan del negocio. |
| 500 | Fallo al Procesar el Registro de un Cliente | No se pudo registrar el cliente nuevo. |
| 500 | Error guardando las notas de entrega, intente más tarde. | Falló la transacción en la base de datos. |
Notas
- Cliente. Se busca por
documentoIdentidadClientedentro del negocio. Si no existe, se registra con los datos enviados; si ya existe, se usan los datos registrados (no se actualizan). - Productos. Se buscan por
codigoProducto; si no existen, se crean con el nombre, la descripción, el precio y la alícuota enviados. Si el código ya existe, la alícuota con la que se agrupa la línea es la del producto registrado: usa siempre el mismotipoImpuestopara un mismo código. - Cálculo. Base de cada línea =
precioProducto×cantidadAdquirida; IVA por alícuota. - Tasa de cambio. La orden toma la tasa de cambio configurada en el negocio; no se envía en la solicitud.
- Número ya usado. Si un
numeroDeNotaDeEntregaya existe en el negocio o se repite en el envío, esa orden no se guarda y su número aparece endelivery_note_errors; si se guardó al menos una, la respuesta es"success": true. Si todas estaban registradas: HTTP409,"success": falseyLas notas de entrega ya están registradas. - Empleados. Chofer y despachador se identifican por su
correo; usa siempre el mismo correo para la misma persona. - Si la firma electrónica falla, la orden se guarda igualmente.
