API de notas de empaque PDF para flujos de fulfillment
Genere notas de empaque PDF desde datos de pedido, envío, caja y artículos para flujos de fulfillment de ecommerce, 3PL, OMS y almacén.
/api/v1/template-render Renderizar notas de empaque desde datos de envío, destinatario, artículos y cajas, para que los equipos de fulfillment puedan imprimir o adjuntar un documento consistente en cada pedido saliente.
Cuándo usar esta API
- Su OMS o WMS ya tiene artículos del pedido, cantidades, datos del destinatario e identificadores de envío.
- Necesita una nota de empaque PDF para estaciones de impresión de almacén o insertos dentro del paquete.
- Quiere reutilizar un diseño aprobado entre almacenes, marcas o canales de venta.
- Puede necesitar un código de barras o QR para búsqueda de pedidos o recepción de devoluciones.
Qué no sustituye
- Necesita comprar portes, calcular una tarifa de envío o crear una etiqueta de transportista.
- Necesita gestión de inventario de almacén en lugar de renderizado de documentos.
- Necesita semántica de factura legal o factura electrónica.
Qué endpoint llamar
/api/v1/template-render
Template Render es la ruta predeterminada para este flujo.
/api/v1/pdf/render
Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.
Solicitud mínima
POST /api/v1/template-render - plantilla packing_list con un envío.
{
"template_id": "packing_list",
"data": [
{
"shipment": {
"number": "PL-2026-1001",
"date": "2026-05-29"
},
"shipper": {
"name": "Acme Warehouse",
"address": "1200 Logistics Pkwy"
},
"consignee": {
"name": "Receiver Inc.",
"address": "123 Main St"
},
"items": [
{
"item_no": "1",
"description": "Replacement filter",
"quantity": "2",
"unit": "pcs",
"gross_weight": "1.2 kg",
"net_weight": "1.0 kg"
}
]
}
]
}
Qué gestiona gPdf
- Template Render para diseños publicados de notas de empaque.
- JSON Render para páginas de notas de empaque personalizadas durante el diseño o flujos puntuales.
- Tablas, filas de artículos, bloques de dirección, códigos de barras opcionales y salida PDF.
- Reimpresiones deterministas cuando se usan los mismos datos y la misma plantilla.
Qué controla su sistema
- Datos del pedido, cantidades de artículos, estado del envío, enrutamiento de almacén y mensajes al cliente.
- Mapeo de campos de la plantilla, enrutamiento de estaciones de impresión y política de reimpresión.
- Cualquier documento de transportista, aduanas o factura que deba viajar con el paquete.
Checklist de producción
- Pruebe las combinaciones más largas de SKU, nombre de artículo y dirección.
- Valide casos de un solo artículo, varias cajas, pedidos pendientes y envíos parciales.
- Use Template Render después de aprobar el diseño de la nota de empaque.
- Registre `template_id` y X-Request-Id en cada solicitud de impresión de fulfillment.
- Mantenga la generación de etiquetas de transportista separada del renderizado de notas de empaque.
Límites de la promesa
- gPdf renderiza el PDF de la nota de empaque; no gestiona inventario ni estado de fulfillment.
- Una nota de empaque no es automáticamente una factura fiscal ni un documento aduanero.
- La compra de etiquetas de transportista y el cálculo de tarifas de envío quedan fuera de gPdf.
Las notas de empaque encajan con la ruta de plantillas
Las notas de empaque suelen tener una estructura estable: remitente, destinatario, número de envío, filas de artículos y notas opcionales. Por eso Template Render encaja especialmente bien después de aprobar el diseño.
JSON Render sigue siendo útil durante el diseño. Permite ajustar columnas,
espaciado, ubicación de códigos de barras y saltos de página antes de publicar
el contrato estable de template_id.
FAQ
- ¿Una nota de empaque es un endpoint separado de gPdf?
- No. Use Template Render para una plantilla de nota de empaque aprobada o JSON Render cuando su sistema describa el diseño directamente.
- ¿Las notas de empaque pueden incluir códigos de barras?
- Sí. gPdf puede renderizar elementos de código de barras en el PDF. Su sistema conserva la responsabilidad sobre el pedido, la caja o los datos de devolución codificados.
- ¿gPdf crea etiquetas de transportista?
- No. Las etiquetas de transportista son un flujo separado. gPdf renderiza PDF a partir de los datos que proporciona su transportista o sistema de envíos.
- ¿Una solicitud puede renderizar varias notas de empaque?
- Template Render acepta un array `data` para varios elementos en una sola solicitud, dentro de los límites públicos de la API documentados para ese endpoint.