API de etiquetas de devolución para logística inversa ecommerce
Genere PDF de etiquetas de devolución e instrucciones de devolución desde datos de ecommerce o soporte, con páginas de tamaño etiqueta, códigos de barras y reimpresiones mediante plantilla.
/api/v1/pdf/render Renderizar PDF de etiquetas de devolución u hojas de instrucciones desde datos de RMA, cliente, artículo, destino y código de barras, para que un portal de devoluciones pueda entregar al cliente un documento determinista.
Cuándo usar esta API
- Su sistema ya creó la RMA y la autorización de devolución.
- Un transportista o sistema de devoluciones ya proporcionó los datos de etiqueta o seguimiento.
- Necesita una etiqueta PDF u hoja de instrucciones que pueda descargarse, enviarse por email o reimprimirse.
- Quiere reutilizar el mismo diseño de etiqueta de devolución mediante Template Render.
Qué no sustituye
- Necesita que gPdf apruebe la devolución, compre portes o cree un envío de transportista.
- Necesita orquestación directa de APIs de transportistas.
- Necesita salida en comandos de impresora, como ZPL.
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 de devolución con código de barras RMA.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 5,
"y": 8,
"content": "RETURN TO",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 5,
"y": 18,
"content": "Acme Returns\n500 Dock Door 4\nColumbus OH 43215",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "RMA-2026-77881",
"x": 5,
"y": 70,
"width": 88,
"height": 20,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
Qué gestiona gPdf
- Renderizado PDF para etiquetas de devolución de tamaño etiqueta y páginas de instrucciones.
- Bloques de código de barras, texto, dirección, RMA y servicio.
- Vinculación con plantillas para diseños aprobados de etiquetas o instrucciones de devolución.
- Salida determinista para redescargas de clientes y reimpresiones de soporte.
Qué controla su sistema
- Elegibilidad de devolución, estado de RMA, cuenta de transportista, portes, número de seguimiento y mensajes al cliente.
- Datos correctos del código de barras, dirección de destino, referencias de artículos y reglas de ventana de devolución.
- Entrega por email, descarga en portal y trazabilidad de soporte.
Checklist de producción
- Valide los datos de devolución con el transportista o proveedor de devoluciones antes de renderizar.
- Imprima y escanee etiquetas en el mismo material que usarán clientes o tiendas.
- Incluya un X-Request-Id y guarde la traza RMA-a-PDF en sus logs de soporte.
- Haga que las descargas repetidas sean idempotentes desde la perspectiva del cliente.
- Separe el renderizado de la etiqueta de la lógica de aprobación del reembolso.
Límites de la promesa
- gPdf renderiza PDF de etiquetas de devolución; no autoriza devoluciones ni compra portes.
- La aceptación del transportista y la corrección de los datos del código de barras siguen siendo su responsabilidad.
- La API pública devuelve PDF, no ZPL ni comandos directos de impresora.
La logística inversa necesita responsabilidades claras
Las etiquetas de devolución combinan experiencia de cliente y reglas de transportista. gPdf se encarga del renderizado PDF. Su sistema de devoluciones mantiene la elegibilidad, el estado de RMA, el seguimiento, los datos del transportista y la comunicación con el cliente.
Mantenga esa frontera visible en la integración. Genere primero la decisión de devolución y después renderice el documento desde los datos ya finalizados.
FAQ
- ¿gPdf crea el envío de devolución?
- No. Su transportista o plataforma de devoluciones crea el envío y los datos. gPdf renderiza esos datos como PDF.
- ¿Las etiquetas de devolución pueden generarse desde plantillas?
- Sí. Use Template Render cuando el diseño de la etiqueta o de las instrucciones de devolución esté aprobado.
- ¿El PDF puede incluir instrucciones de devolución?
- Sí. La misma solicitud de renderizado puede crear una página de etiqueta, una página de instrucciones o ambas, según su diseño.
- ¿gPdf sustituye la certificación del transportista?
- No. La aceptación del transportista, las pruebas de escaneo y las reglas de datos siguen siendo su responsabilidad.