API de etiquetas de envío para etiquetas PDF 4x6
Genere etiquetas de envío PDF 4x6 listas para imprimir a partir de JSON de pedidos, con códigos de barras vectoriales, tamaños de página para etiquetas y reimpresiones de almacén deterministas.
/api/v1/pdf/render Renderizar PDF con tamaño de etiqueta desde datos de pedido, destinatario, servicio y seguimiento, para que un backend de almacén o ecommerce pueda imprimir la misma etiqueta 4x6 de forma fiable durante el fulfillment y volver a generarla de manera determinista cuando haga falta.
Cuándo usar esta API
- Su sistema ya tiene el número de seguimiento, el destino, el texto del servicio y los datos que debe codificar el código de barras.
- Necesita salida PDF para flujos con Zebra, SATO, Honeywell u otras impresoras térmicas.
- Quiere módulos de código de barras vectoriales en lugar de imágenes raster pegadas dentro de un PDF.
- Necesita que los mismos datos generen la misma etiqueta para reimpresiones y evidencia de auditoría.
Qué no sustituye
- Necesita comprar portes, calcular una tarifa de envío o crear una etiqueta de transportista mediante una cuenta de transportista.
- Necesita un endpoint que sustituya ZPL. gPdf devuelve PDF, no lenguaje de comandos de impresora.
- Necesita certificación de transportista emitida por gPdf. Las pruebas de escaneo y aceptación del transportista siguen siendo su responsabilidad.
Qué endpoint llamar
/api/v1/pdf/render
JSON Render es la ruta predeterminada para este flujo.
/api/v1/template-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/pdf/render - etiqueta 4x6 mínima con código de barras de seguimiento.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 4,
"y": 6,
"content": "SHIP TO",
"style": { "font_size": 8, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 4,
"y": 13,
"content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "1Z999AA10123456784",
"x": 4,
"y": 62,
"width": 92,
"height": 22,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
Qué gestiona gPdf
- Páginas PDF con tamaño de etiqueta, incluidos flujos de 4x6 pulgadas.
- Renderizado vectorial de códigos de barras para contenido de transportistas y almacenes.
- Texto, bloques de dirección, marcas de servicio, líneas, cajas y vinculación opcional con plantillas.
- Salida PDF determinista para reimpresiones de almacén.
Qué controla su sistema
- Cuenta de transportista, compra de portes, selección de servicio y creación del número de seguimiento.
- Datos correctos para el código de barras, texto legible, direcciones y datos de enrutamiento.
- Configuración de impresoras, material de etiquetas, pruebas de escaneo y validaciones de aceptación del transportista.
Checklist de producción
- Imprima etiquetas de prueba en el modelo real de impresora y con el material real de etiquetas.
- Verifique las tasas de lectura del código de barras al DPI objetivo y a la distancia real del escáner.
- Guarde los datos fuente del envío o el PDF devuelto según su política de reimpresión.
- Use Template Render cuando el diseño de la etiqueta esté aprobado y se reutilice entre sistemas.
- Mantenga la lógica específica del transportista fuera de la solicitud de renderizado.
Límites de la promesa
- gPdf renderiza el PDF de la etiqueta; no compra portes ni habla directamente con transportistas.
- gPdf no es una autoridad de certificación de etiquetas de transportista.
- La API devuelve PDF, no ZPL, EPL ni otro flujo de comandos para impresoras térmicas.
Estructura de la API de etiquetas de envío
Las páginas de etiquetas de envío no son un endpoint de transportista separado. Usted llama a JSON Render con una página de tamaño de etiqueta, bloques de texto, líneas, imágenes opcionales y elementos de código de barras. Para etiquetas repetidas, publique el diseño aprobado como plantilla y llame a Template Render con los datos del envío.
Esto mantiene clara la responsabilidad. gPdf se encarga de renderizar el PDF y dibujar los códigos de barras. Su sistema conserva la transacción con el transportista, el estado del envío y la semántica de los datos.
JSON Render frente a Template Render
Use JSON Render cuando su sistema de fulfillment genere el diseño completo o cuando el equipo de operaciones todavía esté ajustando coordenadas. Use Template Render cuando el almacén haya aprobado un diseño de etiqueta estable y todos los clientes deban enviar los mismos campos de datos.
Ambas rutas devuelven PDF. La diferencia es si quien llama describe el diseño
en cada solicitud o referencia un template_id publicado.
Las pruebas de impresión importan
La calidad de una etiqueta térmica es física. Valide la salida con el material de etiquetas real, las impresoras reales y los escáneres reales. La corrección de los datos del código de barras, las zonas silenciosas, la densidad de impresión y las reglas específicas de cada transportista son responsabilidades de producción fuera de la API de renderizado.
FAQ
- ¿gPdf crea etiquetas de transportista por mí?
- No. Su transportista o sistema de envíos crea el envío y los datos del código de barras. gPdf renderiza esos datos como una etiqueta PDF.
- ¿Puedo usar Template Render para etiquetas de envío?
- Sí. Use JSON Render mientras diseña o prueba la etiqueta, y pase a Template Render cuando el diseño sea estable y los clientes solo deban enviar datos.
- ¿gPdf devuelve ZPL?
- No. Las APIs públicas de renderizado devuelven PDF. Si su ruta de impresión necesita ZPL, convierta o enrute el PDF fuera de gPdf.
- ¿Qué debo validar antes de producción?
- Imprima en la impresora y el material de etiquetas reales, escanee el código de barras con escáneres de producción y confirme que el texto y los datos específicos del transportista provienen de su sistema de envíos.