Skip to content

Guía de despacho ​

POST /api/Invoice/add_list_dispatch_guide

Emite guías de despacho: documentos que acompañan el traslado de mercancía a un cliente. Envías el cliente, los productos, el origen y destino, el vehículo, el chofer y el despachador. Admite varias guías por solicitud; cada una recibe un número de control y se firma electrónicamente. Devuelve, por cada guía guardada, su número de control y el enlace al PDF.

Si el chofer, el despachador o el vehículo no se conocen al emitir, usa Guía de despacho opcional.

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").
cantidadGDPintegerSíCantidad de guías enviadas. Debe ser un entero e igual al número de elementos de guiasDeDespacho.
guiasDeDespachoarraySíGuías a emitir. Al menos una. Ver guiasDeDespacho[].

guiasDeDespacho[] ​

CampoTipoObligatorioDescripción y reglas
numeroDeGuiaDeDespachostringSíNúmero que tendrá la guía. 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".
origenstringRecomendadoLugar de origen del traslado. El API no lo valida, pero se imprime en la guía.
destinostringRecomendadoLugar de destino del traslado. El API no lo valida, pero se imprime en la guía.
productosarraySíProductos que se despachan. 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 guía. Si no existe en el negocio, el producto se crea.
nombreProductostringSíNombre del producto, máximo 400 caracteres.
descripcionProductostringSíDescripción que se imprime en la línea, máximo 400 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 "2,55" o "150.50"). 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",
  "cantidadGDP": 1,
  "guiasDeDespacho": [
    {
      "numeroDeGuiaDeDespacho": "000047",
      "documentoIdentidadCliente": "J123456789",
      "nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
      "correoCliente": "compras@example.com",
      "direccionCliente": "Av. Principal, Edificio Ejemplo, Caracas",
      "telefonoCliente": "04141234567",
      "origen": "Almacén principal, Guarenas",
      "destino": "La Guaira",
      "productos": [
        {
          "codigoProducto": "CAF-0001",
          "nombreProducto": "CAFE",
          "descripcionProducto": "CAFE MOLIDO 500 G",
          "tipoImpuesto": "G",
          "cantidadAdquirida": 10,
          "precioProducto": "2,55"
        }
      ],
      "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": "ROJO",
        "codigoVehiculo": "CAM-001"
      }
    }
  ]
}

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Guías de despacho guardadas satisfactoriamente",
  "dispatch_guide_errors": [],
  "dispatch_guide_success": [
    {
      "dispatch_guide_number": "000047",
      "control_number": "00-00000130",
      "dispatch_guide_pdf": "https://api.example.com/readonly/export_pdf/3d9a6c1e-8f2b-4a07-a5c3-e9d1a4f6b820"
    }
  ]
}
ClaveDescripción
successtrue si se guardó al menos una guía. Si todas estaban registradas: false con HTTP 409.
messageGuías de despacho guardadas satisfactoriamente, o Las guías de despacho se guardaron correctamente, pero algunas estaban duplicadas y no pudieron guardarse si alguna se rechazó.
dispatch_guide_errorsArreglo con los numeroDeGuiaDeDespacho no guardados porque ya existían en el negocio o estaban repetidos en el envío.
dispatch_guide_successUna entrada por guía guardada: dispatch_guide_number, control_number (serie-########) y dispatch_guide_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 guía se identifica por su numeroDeGuiaDeDespacho.

HTTPMensaje (ejemplo)Causa
400El campo Número de Serie es obligatorio.Falta numeroSerie.
400El campo Cantidad de Guías de Despacho es obligatorio.Falta cantidadGDP (si no es entero: El campo Cantidad de Guías de Despacho debe ser un número entero.).
400El campo Guías de Despacho es obligatorio y no debe estar vacío.Falta guiasDeDespacho o está vacío.
400La cantidad de productos por guía de despacho 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 guias_error con numeroDeGuiaDeDespacho y cantidadProductos de cada guía excedida.
400El campo Número de Guía de Despacho en la guía 1 debe contener solo números enteros (sin decimales, espacios, letras ni caracteres especiales). Valor recibido: GD-47.Número de guía inválido (también hay mensajes de obligatorio y de máximo 19 caracteres).
400El Documento de Identidad del Cliente en la guía 000047 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 guía 000047 es inválido incluso después de limpieza. Valor recibido: ...Correo del cliente inválido.
400El campo Teléfono del Cliente en la guía 000047 es obligatorio.Falta un dato del cliente (análogos para Nombre o Razón Social, Correo y Dirección).
400El campo Productos en la guía 000047 es obligatorio y no debe estar vacío.Falta productos.
400El campo Código del Producto en el producto 1 de la guía 000047 no puede exceder los 13 caracteres.Dato de producto inválido (hay mensajes análogos para nombre, descripción, tipo de impuesto, cantidad y precio).
400El campo Cantidad Adquirida en el producto 1 de la guía 000047 debe ser mayor que cero. Valor recibido: 0.Cantidad no válida.
400El campo Trabajador en la guía 000047 es obligatorio y no debe estar vacío.Falta empleados.
400El Documento de Identidad del Trabajador en la guía 000047 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 Correo del Trabajador en la guía 000047 debe contener un correo electrónico válido.Correo del empleado inválido.
400El campo Vehículo en la guía 000047 es obligatorio y no debe estar vacío.Falta vehiculo (si falta un dato: El campo Placa del Vehículo en la guía 000047 es obligatorio., etc.).
400La guía de despacho 000047 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 guías de despacho incorrecta.cantidadGDP no coincide con el número de guías enviadas.
400Error: Productos duplicados en la misma guía de despacho.Un codigoProducto se repite dentro de la misma guía.
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 guías de despacho, intente más tarde.Falló la transacción en la base de datos.

Notas ​

  • Varias guías por solicitud. Cada guía del arreglo se guarda con sus propios datos: cliente, productos, origen, destino, vehículo, chofer y despachador.
  • 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 los datos 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.
  • Número ya usado. Si un numeroDeGuiaDeDespacho ya existe en el negocio o se repite en el envío, esa guía no se guarda y su número aparece en dispatch_guide_errors; si se guardó al menos una, la respuesta es "success": true. Si todas estaban registradas: HTTP 409, "success": false y Las guías de despacho 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 guía se guarda igualmente.

API de Facturación · CG Imprenta Digital