Skip to content

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 ​

CampoTipoObligatorioDescripción y reglas
numeroSeriestringSíCódigo de la serie de numeración del negocio (por ejemplo "A").
cantidadNEintegerSíCantidad de órdenes enviadas. Debe ser un entero e igual al número de elementos de notasDeEntregas.
notasDeEntregasarraySíÓrdenes a emitir. Al menos una. Ver notasDeEntregas[].

notasDeEntregas[] ​

CampoTipoObligatorioDescripción y reglas
numeroDeNotaDeEntregastringSí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.
documentoIdentidadClientestringSí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.
nombreRazonSocialClientestringSíNombre o razón social del cliente.
correoClientestringSíCorreo del cliente. Se normaliza (minúsculas, sin espacios ni caracteres no permitidos) y debe quedar como un correo válido.
direccionClientestringSíDirección fiscal del cliente.
telefonoClientestringSíTeléfono del cliente, por ejemplo "04141234567".
origenstringSíLugar de origen del traslado.
destinostringSíLugar de destino del traslado.
productosarraySíProductos que se entregan. Al menos uno. Ver productos[].
empleadosarraySíDebe incluir al menos un chofer y un despachador. Ver empleados[].
vehiculoobjectSíDatos del vehículo. Ver vehiculo.

productos[] ​

CampoTipoObligatorioDescripción y reglas
codigoProductostringSí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.
nombreProductostringSíNombre del producto, máximo 70 caracteres.
descripcionProductostringSíDescripción que se imprime en la línea, máximo 70 caracteres.
tipoImpuestostringSíAlícuota de IVA: E (exento, 0 %), R (reducida, 8 %), G (general, 16 %), A (adicional, 31 %), P (percibido, 0 %).
cantidadAdquiridanumber o stringSíCantidad mayor que 0, con punto decimal (por ejemplo 10 o "2.50"). Sin signo ni separadores de miles.
precioProductostringSí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[] ​

CampoTipoObligatorioDescripción y reglas
nombrestringSíNombre del empleado.
apellidostringSíApellido del empleado.
DocumentoIdentidadstringSíLetra V, E, P, J, G o C seguida de exactamente 8 dígitos. 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.

vehiculo ​

CampoTipoObligatorioDescripción y reglas
placaVehiculostringSíPlaca del vehículo.
tipoVehiculostringSíTipo de vehículo.
colorVehiculostringSíColor del vehículo.
codigoVehiculostringSí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"
    }
  ]
}
ClaveDescripción
successtrue si se guardó al menos una orden. Si todas estaban registradas: false con HTTP 409.
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ó.
delivery_note_errorsArreglo con los numeroDeNotaDeEntrega no guardados porque ya existían en el negocio o estaban repetidos en el envío.
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. En los mensajes, la orden se identifica por su numeroDeNotaDeEntrega.

HTTPMensaje (ejemplo)Causa
400El campo Número de Serie es obligatorio.Falta numeroSerie.
400El 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.).
400El campo Notas de Entrega es obligatorio y no debe estar vacío.Falta notasDeEntregas o está vacío.
400La cantidad de productos por nota de entrega no puede ser mayor a 50Se 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.
400El 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: V12345678Documento del cliente inválido.
400El campo Correo del Cliente en la nota 000101 es inválido incluso después de limpieza. Valor recibido: ...Correo del cliente inválido.
400El 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).
400El campo Productos en la nota 000101 es obligatorio y no debe estar vacío.Falta productos.
400El 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).
400El 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.
400El campo Trabajador en la nota 000101 es obligatorio y no debe estar vacío.Falta empleados.
400El 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: V12345678Documento del empleado inválido.
400El 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.).
400La nota de entrega 000101 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.
400Cantidad de notas de entrega incorrecta.cantidadNE no coincide con el número de órdenes enviadas.
400Error: Productos duplicados en la misma nota de entrega.Un codigoProducto se repite dentro de la misma orden.
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.
500Fallo al Procesar el Registro de un ClienteNo se pudo registrar el cliente nuevo.
500Error guardando las notas de entrega, intente más tarde.Falló la transacción en la base de datos.

Notas ​

  • Cliente. Se busca por documentoIdentidadCliente dentro 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 mismo tipoImpuesto para 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 numeroDeNotaDeEntrega ya existe en el negocio o se repite en el envío, esa orden no se guarda y su número aparece en delivery_note_errors; si se guardó al menos una, la respuesta es "success": true. Si todas estaban registradas: HTTP 409, "success": false y Las 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.

API de Facturación · CG Imprenta Digital