Skip to content

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 ​

CampoTipoObligatorioDescripción y reglas
numeroSeriestringSí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.
notasDeEntregasarraySíÓrdenes de entrega a emitir. Al menos una. Ver notasDeEntregas[]. Se recomienda enviar una sola orden por solicitud (ver Notas).

notasDeEntregas[] ​

CampoTipoObligatorioDescripción y reglas
numeroFacturaAfectarstringSí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.
numeroDeNotaDeEntregastringSíNúmero que tendrá la orden de entrega. Solo dígitos, máximo 19 caracteres.
origenstringSíLugar de origen del traslado (ciudad, dirección, almacén).
destinostringSíLugar de destino del traslado.
vehiculoobjectSíDatos del vehículo. Ver vehiculo.
empleadosarraySíPersonas a cargo de la entrega. Debe incluir al menos un empleado con cargo chofer y uno con cargo despachador. Ver empleados[].

vehiculo ​

CampoTipoObligatorioDescripción y reglas
placaVehiculostringSíPlaca del vehículo.
tipoVehiculostringSíTipo de vehículo (por ejemplo "CAMION", "GANDOLA").
colorVehiculostringSíColor del vehículo.
codigoVehiculostringSíCódigo interno del vehículo.

empleados[] ​

CampoTipoObligatorioDescripción y reglas
nombrestringSíNombre del empleado.
apellidostringSíApellido del empleado.
DocumentoIdentidadstringSíLetra V, E, P, J, G o C seguida de 7 a 9 dígitos, sin guiones ni espacios. Ejemplo: V12345678.
cargostringSíchofer o despachador (no distingue mayúsculas: Chofer también vale).
correostringSí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"
    }
  ]
}
ClaveDescripción
successtrue si se guardó al menos una orden; false (HTTP 409) si todas estaban registradas.
messageNotas 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_errorsArreglo con los numeroDeNotaDeEntrega que no se guardaron porque ese número ya existía en el negocio.
delivery_note_successUna entrada por orden guardada: delivery_note_number, control_number (serie-########) y delivery_note_pdf.
warning_control_numbersSolo 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.

HTTPMensaje (ejemplo)Causa
400El campo Número de Serie es obligatorio.Falta numeroSerie.
400El campo Notas de Entrega es obligatorio y no debe estar vacío.Falta notasDeEntregas o está vacío.
400El 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).
400El 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.
400El campo Origen en la nota de entrega 1 es obligatorio.Falta origen (análogo para Destino).
400El 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).
400El campo Empleados en la nota de entrega 1 es obligatorio y no debe estar vacío.Falta empleados.
400El 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).
400El 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: V12345678Documento con formato inválido.
400El campo Correo del Empleado en la nota de entrega 1, empleado 1 debe contener un correo electrónico válido.Correo inválido.
400Si se incluyen empleados, la nota de entrega 1 necesita un chofer y un despachador.Falta un chofer o un despachador.
400Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, ...El negocio no tiene configurado su tipo de contribuyente.
401 / 400Ver ErroresToken ausente, mal formado, inválido o vencido.
400Error: Facturas duplicadas en la entrada JSON.El mismo numeroFacturaAfectar aparece dos veces en el envío.
404El número de factura no existe.No hay una factura del negocio con ese número.
409Ya esta factura posee una nota de entrega.Ver Notas.
409El comercio no posee más números de control activos.Se agotaron los números de control durante el proceso.
409No existe un número de control asociado al comercio.El negocio no tiene números de control.
404El comercio indicado aún no está registrado.No se encontró el negocio del token.
409Paquete incorrectoAl registrar un chofer o despachador nuevo se superó el límite de usuarios del plan del negocio.
500Error 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 numeroDeNotaDeEntrega ya existe en el negocio, esa orden no se guarda y su número aparece en delivery_note_errors. Si todas estaban registradas, la respuesta es HTTP 409 con "success": false y El número de nota de entrega ya está en uso. Comprueba siempre delivery_note_success y delivery_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 el numeroFacturaAfectar, 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.

API de Facturación · CG Imprenta Digital