API de etiqueta de devolução para logística reversa de ecommerce
Gere PDFs de etiqueta de devolução e instruções de devolução a partir de dados de ecommerce ou suporte, com páginas em tamanho de etiqueta, códigos de barras e reimpressões por modelo.
/api/v1/pdf/render Renderizar PDFs de etiqueta de devolução ou folhas de instrução a partir de dados de RMA, cliente, item, destino e código de barras, para que um portal de devoluções entregue ao cliente um documento determinístico.
Quando usar esta API
- Seu sistema já criou o RMA e a autorização de devolução.
- Uma transportadora ou sistema de devoluções já forneceu os dados da etiqueta ou de rastreamento.
- Você precisa de uma etiqueta PDF ou folha de instruções que possa ser baixada, enviada por e-mail ou reimpressa.
- Você quer reutilizar o mesmo layout de etiqueta de devolução por meio de Template Render.
O que ela não substitui
- Você precisa que o gPdf aprove a devolução, compre postagem ou crie um envio de transportadora.
- Você precisa de orquestração direta de API de transportadora.
- Você precisa de saída de comandos de impressora, como ZPL.
Qual endpoint chamar
/api/v1/pdf/render
JSON Render é o caminho padrão para este fluxo.
/api/v1/template-render
Use quando o fluxo precisar da API relacionada, de um contrato de template ou de uma consulta de capacidades.
Request mínimo
POST /api/v1/pdf/render - etiqueta de devolução com 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" }
}
]
}
]
}
O que a gPdf faz
- Renderização em PDF para etiquetas de devolução em tamanho de etiqueta e páginas de instrução.
- Blocos de código de barras, texto, endereço, RMA e serviço.
- Vinculação a modelo para layouts aprovados de etiqueta de devolução ou instruções.
- Saída determinística para novos downloads pelo cliente e reimpressões de suporte.
O que seu sistema controla
- Elegibilidade da devolução, estado do RMA, conta da transportadora, postagem, número de rastreamento e mensagens ao cliente.
- Dados corretos para o código de barras, endereço de destino, referências dos itens e regras da janela de devolução.
- Entrega por e-mail, download no portal e trilha de auditoria do suporte.
Checklist de produção
- Valide os dados de devolução com a transportadora ou provedor de devoluções antes da renderização.
- Imprima e escaneie etiquetas na mesma mídia que clientes ou lojas vão usar.
- Inclua um X-Request-Id e armazene o vínculo RMA-PDF nos logs de suporte.
- Torne downloads repetidos idempotentes do ponto de vista do cliente.
- Separe a renderização da etiqueta da lógica de aprovação de reembolso.
Limites da promessa
- O gPdf renderiza PDFs de etiqueta de devolução; ele não autoriza devoluções nem compra postagem.
- Aceite da transportadora e correção dos dados codificados no código de barras continuam sob sua responsabilidade.
- A API pública retorna PDF, não ZPL nem comandos diretos de impressora.
Logística reversa precisa de responsabilidade clara
Etiquetas de devolução combinam experiência do cliente e regras da transportadora. O gPdf responde pela renderização do PDF. Seu sistema de devoluções responde por elegibilidade, estado do RMA, rastreamento, dados da transportadora e comunicação com o cliente.
Mantenha essa fronteira visível na integração. Gere primeiro a decisão de devolução; depois renderize o documento a partir dos dados finalizados.
FAQ
- O gPdf cria o envio de devolução?
- Não. Sua transportadora ou plataforma de devoluções cria o envio e os dados codificados. O gPdf renderiza esses dados em um PDF.
- Etiquetas de devolução podem ser geradas por modelos?
- Sim. Use Template Render depois que o layout da etiqueta de devolução ou das instruções for aprovado.
- O PDF pode incluir instruções de devolução?
- Sim. A mesma requisição de renderização pode criar uma página de etiqueta, uma página de instruções ou ambas, dependendo do seu layout.
- O gPdf substitui certificação de transportadora?
- Não. Aceite da transportadora, testes de scanner e regras dos dados codificados continuam sob sua responsabilidade.