Apariencia
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
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroSerie | string | Sí | Código de la serie de numeración del negocio (por ejemplo "A"). |
cantidadGDP | integer | Sí | Cantidad de guías enviadas. Debe ser un entero e igual al número de elementos de guiasDeDespacho. |
guiasDeDespacho | array | Sí | Guías a emitir. Al menos una. Ver guiasDeDespacho[]. |
guiasDeDespacho[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroDeGuiaDeDespacho | string | Sí | 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. |
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 | Recomendado | Lugar de origen del traslado. El API no lo valida, pero se imprime en la guía. |
destino | string | Recomendado | Lugar de destino del traslado. El API no lo valida, pero se imprime en la guía. |
productos | array | Sí | Productos que se despachan. 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 guía. Si no existe en el negocio, el producto se crea. |
nombreProducto | string | Sí | Nombre del producto, máximo 400 caracteres. |
descripcionProducto | string | Sí | Descripción que se imprime en la línea, máximo 400 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 "2,55" o "150.50"). 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",
"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"
}
]
}| Clave | Descripción |
|---|---|
success | true si se guardó al menos una guía. Si todas estaban registradas: false con HTTP 409. |
message | Guí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_errors | Arreglo con los numeroDeGuiaDeDespacho no guardados porque ya existían en el negocio o estaban repetidos en el envío. |
dispatch_guide_success | Una entrada por guía guardada: dispatch_guide_number, control_number (serie-########) y dispatch_guide_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 guía se identifica por su numeroDeGuiaDeDespacho.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Número de Serie es obligatorio. | Falta numeroSerie. |
| 400 | El 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.). |
| 400 | El campo Guías de Despacho es obligatorio y no debe estar vacío. | Falta guiasDeDespacho o está vacío. |
| 400 | La cantidad de productos por guía de despacho 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 guias_error con numeroDeGuiaDeDespacho y cantidadProductos de cada guía excedida. |
| 400 | El 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). |
| 400 | El 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: V12345678 | Documento del cliente inválido. |
| 400 | El campo Correo del Cliente en la guía 000047 es inválido incluso después de limpieza. Valor recibido: ... | Correo del cliente inválido. |
| 400 | El 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). |
| 400 | El campo Productos en la guía 000047 es obligatorio y no debe estar vacío. | Falta productos. |
| 400 | El 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). |
| 400 | El campo Cantidad Adquirida en el producto 1 de la guía 000047 debe ser mayor que cero. Valor recibido: 0. | Cantidad no válida. |
| 400 | El campo Trabajador en la guía 000047 es obligatorio y no debe estar vacío. | Falta empleados. |
| 400 | El 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: V12345678 | Documento del empleado inválido. |
| 400 | El campo Correo del Trabajador en la guía 000047 debe contener un correo electrónico válido. | Correo del empleado inválido. |
| 400 | El 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.). |
| 400 | La guía de despacho 000047 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 guías de despacho incorrecta. | cantidadGDP no coincide con el número de guías enviadas. |
| 400 | Error: Productos duplicados en la misma guía de despacho. | Un codigoProducto se repite dentro de la misma guía. |
| 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 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
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 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 mismotipoImpuestopara un mismo código. - Cálculo. Base de cada línea =
precioProducto×cantidadAdquirida; IVA por alícuota. - Número ya usado. Si un
numeroDeGuiaDeDespachoya existe en el negocio o se repite en el envío, esa guía no se guarda y su número aparece endispatch_guide_errors; si se guardó al menos una, la respuesta es"success": true. Si todas estaban registradas: HTTP409,"success": falseyLas 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.
