API de etiqueta de envio para etiquetas PDF 4x6
Gere PDFs de etiquetas de envio 4x6 prontos para impressão a partir de JSON de pedido, com códigos de barras vetoriais, tamanhos de página de etiqueta e reimpressões determinísticas no armazém.
/api/v1/pdf/render Renderizar PDFs em tamanho de etiqueta a partir de dados de pedido, destinatário, serviço e rastreamento, para que um armazém ou backend de ecommerce imprima a mesma etiqueta 4x6 com confiabilidade durante o fulfillment e a reimprima de forma determinística quando necessário.
Quando usar esta API
- Seu sistema já tem o número de rastreamento, destino, texto do serviço e dados codificados no código de barras.
- Você precisa de saída em PDF para fluxos com Zebra, SATO, Honeywell ou outras impressoras térmicas.
- Você quer módulos de código de barras vetoriais em vez de imagens raster coladas dentro de um PDF.
- Você precisa que os mesmos dados enviados renderizem a mesma etiqueta para reimpressões e evidência de auditoria.
O que ela não substitui
- Você precisa comprar postagem, cotar um envio ou criar uma etiqueta de transportadora por uma conta de transportadora.
- Você precisa de um endpoint que substitua ZPL. O gPdf retorna PDF, não linguagem de comando de impressora.
- Você precisa de certificação de transportadora emitida pelo gPdf. Testes de scanner e aceite da transportadora continuam sob sua responsabilidade.
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 4x6 mínima com código de barras de rastreamento.
{
"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" }
}
]
}
]
}
O que a gPdf faz
- Páginas PDF em tamanho de etiqueta, como fluxos de 4x6 polegadas.
- Renderização vetorial de códigos de barras para conteúdo de etiquetas de transportadora e armazém.
- Texto, blocos de endereço, marcas de serviço, linhas, caixas e vinculação opcional a modelo.
- Saída PDF determinística para reimpressões no armazém.
O que seu sistema controla
- Conta da transportadora, compra de postagem, seleção de serviço e criação do número de rastreamento.
- Dados corretos para o código de barras, texto legível, endereços e dados de roteamento.
- Configuração da impressora, mídia da etiqueta, testes de leitura e verificações de aceite da transportadora.
Checklist de produção
- Imprima etiquetas de teste no modelo real de impressora e na mídia real de etiqueta.
- Verifique as taxas de leitura do código de barras no DPI e na distância de scanner esperados.
- Armazene os dados de envio de origem ou o PDF retornado de acordo com sua política de reimpressão.
- Use Template Render depois que o layout da etiqueta for aprovado e reutilizado por vários sistemas.
- Mantenha lógica específica de transportadora fora da requisição de renderização.
Limites da promessa
- O gPdf renderiza o PDF da etiqueta; ele não compra postagem nem conversa diretamente com transportadoras.
- O gPdf não é uma autoridade de certificação de etiquetas de transportadora.
- A API gera PDF, não ZPL, EPL ou outro fluxo de comandos para impressora térmica.
O formato da API de etiqueta de envio
Páginas de etiqueta de envio não são um endpoint separado de transportadora. Você chama JSON Render com uma página em tamanho de etiqueta, blocos de texto, linhas, imagens opcionais e elementos de código de barras. Para etiquetas repetidas, publique o layout aprovado como modelo e chame Template Render com os dados de envio.
Isso mantém a responsabilidade clara. O gPdf responde pela renderização do PDF e pelo desenho do código de barras. Seu sistema responde pela transação com a transportadora, pelo estado do envio e pela semântica dos dados codificados.
JSON Render versus Template Render
Use JSON Render quando seu sistema de fulfillment gera o layout completo ou quando a equipe de operações ainda está ajustando coordenadas. Use Template Render quando o armazém já aprovou um layout estável de etiqueta e todos os chamadores devem enviar os mesmos campos de dados.
Os dois caminhos retornam saída em PDF. A diferença é se o chamador descreve o
layout em cada requisição ou referencia um template_id publicado.
Testes de impressão importam
Qualidade de etiqueta térmica é física. Valide a saída com a mídia real de etiqueta, as impressoras reais e os scanners reais. Correção dos dados codificados, áreas silenciosas, intensidade da impressora e regras específicas de transportadora são responsabilidades de produção fora da API de renderização.
FAQ
- O gPdf cria etiquetas de transportadora para mim?
- Não. Sua transportadora ou sistema de envio cria o envio da transportadora e os dados codificados no código de barras. O gPdf renderiza esses dados em uma etiqueta PDF.
- Posso usar Template Render para etiquetas de envio?
- Sim. Use JSON Render enquanto desenha ou testa a etiqueta; depois use Template Render quando o layout estiver estável e os chamadores precisarem enviar apenas dados.
- O gPdf gera ZPL?
- Não. As APIs públicas de renderização geram PDF. Se o seu caminho de impressão precisa de ZPL, converta ou roteie o PDF fora do gPdf.
- O que devo validar antes da produção?
- Imprima na impressora e na mídia reais, escaneie o código de barras com scanners de produção e confirme que o texto e os dados específicos da transportadora vêm do seu sistema de envio.