Apariencia
Orden de entrega
POST /api/Invoice/add_list_delivery
Emite órdenes (notas) de entrega asociadas a facturas ya emitidas. Cada orden copia los productos y totales de su factura y registra el traslado: origen, destino, vehículo, chofer y despachador. Cada orden recibe un número de control y se firma electrónicamente. Devuelve, por cada orden guardada, su número de control y el enlace al PDF.
Para una orden de entrega que no depende de una factura, usa Orden de entrega individual.
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í | Serie de numeración (por ejemplo "A"). Es obligatorio, aunque según el código actual en este endpoint la serie de la orden se toma de la factura afectada. |
notasDeEntregas | array | Sí | Órdenes de entrega a emitir. Al menos una. Ver notasDeEntregas[]. Se recomienda enviar una sola orden por solicitud (ver Notas). |
notasDeEntregas[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroFacturaAfectar | string | Sí | Número de la factura que se entrega, exactamente como se registró (se respetan los ceros a la izquierda). Solo dígitos, máximo 19 caracteres. No puede repetirse dentro del mismo envío. |
numeroDeNotaDeEntrega | string | Sí | Número que tendrá la orden de entrega. Solo dígitos, máximo 19 caracteres. |
origen | string | Sí | Lugar de origen del traslado (ciudad, dirección, almacén). |
destino | string | Sí | Lugar de destino del traslado. |
vehiculo | object | Sí | Datos del vehículo. Ver vehiculo. |
empleados | array | Sí | Personas a cargo de la entrega. Debe incluir al menos un empleado con cargo chofer y uno con cargo despachador. Ver empleados[]. |
vehiculo
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
placaVehiculo | string | Sí | Placa del vehículo. |
tipoVehiculo | string | Sí | Tipo de vehículo (por ejemplo "CAMION", "GANDOLA"). |
colorVehiculo | string | Sí | Color del vehículo. |
codigoVehiculo | string | Sí | Código interno del vehículo. |
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 7 a 9 dígitos, sin guiones ni espacios. 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 con ese correo. |
Ejemplo de solicitud
json
{
"numeroSerie": "A",
"notasDeEntregas": [
{
"numeroFacturaAfectar": "000050",
"numeroDeNotaDeEntrega": "000003",
"origen": "Almacén principal, Caracas",
"destino": "Sucursal Valencia",
"vehiculo": {
"placaVehiculo": "AB123CD",
"tipoVehiculo": "CAMION",
"colorVehiculo": "BLANCO",
"codigoVehiculo": "CAM-002"
},
"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"
}
]
}
]
}Respuesta exitosa
HTTP 200
json
{
"success": true,
"message": "Notas de entrega guardadas satisfactoriamente.",
"delivery_note_errors": [],
"delivery_note_success": [
{
"delivery_note_number": "000003",
"control_number": "00-00000128",
"delivery_note_pdf": "https://api.example.com/readonly/export_pdf/6a0d3f9e-1c2b-47d8-a5e4-a7c1f9e03b26"
}
]
}| Clave | Descripción |
|---|---|
success | true si se guardó al menos una orden; false (HTTP 409) si todas estaban registradas. |
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ó; o El número de nota de entrega ya está en uso. si no se guardó ninguna. |
delivery_note_errors | Arreglo con los numeroDeNotaDeEntrega que no se guardaron porque ese número ya existía en el negocio. |
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.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Número de Serie es obligatorio. | Falta numeroSerie. |
| 400 | El campo Notas de Entrega es obligatorio y no debe estar vacío. | Falta notasDeEntregas o está vacío. |
| 400 | El campo Número de Factura a Afectar en la nota de entrega 1 es obligatorio. | Falta numeroFacturaAfectar (hay mensajes de formato y longitud análogos a los de numeroDeNotaDeEntrega). |
| 400 | El campo Número de Nota de Entrega en la nota de entrega 1 debe contener solo números enteros (sin decimales, espacios, letras ni caracteres especiales). Valor recibido: NE-3. | Número de orden con formato inválido. |
| 400 | El campo Origen en la nota de entrega 1 es obligatorio. | Falta origen (análogo para Destino). |
| 400 | El campo Placa del Vehículo en la nota de entrega 1 es obligatorio. | Falta un dato del vehículo (análogos para Tipo, Color y Código del Vehículo). |
| 400 | El campo Empleados en la nota de entrega 1 es obligatorio y no debe estar vacío. | Falta empleados. |
| 400 | El campo Nombre del Empleado en la nota de entrega 1, empleado 2 es obligatorio. | Falta un dato del empleado (análogos para Apellido, Documento de Identidad, Cargo y Correo). |
| 400 | El Documento de Identidad del Empleado en la nota de entrega 1, empleado 1 debe tener el formato correcto (letra seguida de 8 a 9 dígitos). Ejemplo: V12345678 | Documento con formato inválido. |
| 400 | El campo Correo del Empleado en la nota de entrega 1, empleado 1 debe contener un correo electrónico válido. | Correo inválido. |
| 400 | Si se incluyen empleados, la nota de entrega 1 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 | Error: Facturas duplicadas en la entrada JSON. | El mismo numeroFacturaAfectar aparece dos veces en el envío. |
| 404 | El número de factura no existe. | No hay una factura del negocio con ese número. |
| 409 | Ya esta factura posee una nota de entrega. | Ver Notas. |
| 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 | Error guardando la nota de entrega, intente más tarde. | Falló la transacción en la base de datos. |
Notas
- Productos y montos. No se envían productos: la orden copia las líneas, bases, impuestos y totales de la factura afectada, y su cliente.
- Varias órdenes por solicitud. Cada orden del arreglo se guarda con sus propios datos: productos de su factura, origen, destino, vehículo, chofer y despachador.
- Número ya usado. Si el
numeroDeNotaDeEntregaya existe en el negocio, esa orden no se guarda y su número aparece endelivery_note_errors. Si todas estaban registradas, la respuesta es HTTP409con"success": falseyEl número de nota de entrega ya está en uso.Comprueba siempredelivery_note_successydelivery_note_errors. Ya esta factura posee una nota de entrega.Según el código actual, este error se produce cuando existe una orden de entrega del negocio cuyo número coincide con elnumeroFacturaAfectar, no cuando la factura ya tiene una orden asociada.- Empleados. Chofer y despachador se identifican por su
correo. Usa siempre el mismo correo para la misma persona; si el correo ya pertenece a otro tipo de usuario, el empleado puede no quedar asociado a la orden. - Una vez emitida una orden de entrega sobre una factura, según el código actual ya no se puede emitir una nota de crédito total sobre esa factura.
- Si la firma electrónica falla, la orden se guarda igualmente.
