Etiquetas ZPL na prática: como visualizar e converter em PNG e PDF via API

O que é ZPL

ZPL (Zebra Programming Language) é um conjunto de comandos de texto que descreve o conteúdo de uma etiqueta: posições, textos, fontes, linhas e códigos de barras. A impressora recebe esse texto e desenha a etiqueta sozinha. Isso torna a impressão rápida e precisa, e é por isso que transportadoras e marketplaces costumam devolver as etiquetas de envio em ZPL.

Comando	Função
^XA e ^XZ	Início e fim de uma etiqueta
^FO	Posição do campo, em pontos, a partir do canto superior esquerdo
^A0	Fonte e tamanho do texto
^FD e ^FS	Conteúdo do campo e fim do campo
^BC	Código de barras Code 128
^BQ	QR Code
^GB	Caixas e linhas

^XA
^FO40,40^A0N,40,40^FDPedido 58213^FS
^FO40,100^A0N,28,28^FDDestino: Porto Alegre/RS^FS
^FO40,160^BY3^BCN,120,Y,N,N^FD58213000123^FS
^FO40,340^GB730,3,3^FS
^XZ

Tamanho, resolução e pontos

Como o ZPL trabalha em pontos, a mesma etiqueta muda de tamanho conforme a resolução da impressora. Por isso, toda conversão precisa saber três coisas: largura e altura da etiqueta em milímetros e a densidade de impressão, em pontos por milímetro.

Densidade	Resolução equivalente	Uso comum
6 dpmm	152 dpi	Etiquetas simples
8 dpmm	203 dpi	Padrão na maioria das impressoras de expedição
12 dpmm	300 dpi	Etiquetas com textos pequenos e códigos densos
24 dpmm	600 dpi	Aplicações de alta definição

A etiqueta de envio mais comum tem 4 x 6 polegadas, ou seja, 101,6 x 152,4 mm. A 8 dpmm, isso equivale a 812 x 1.219 pontos. Se o ZPL foi escrito para 203 dpi e a impressora é de 300 dpi, tudo sai menor. A pré-visualização com a densidade correta evita esse tipo de surpresa.

O db ZPL: playground e API

O db ZPL tem duas formas de uso. No playground, você cola o ZPL, ajusta tamanho e densidade e vê a etiqueta na hora. Na API, outros sistemas enviam o ZPL e recebem a etiqueta pronta no formato escolhido.

Formato	Retorno	Quando usar
png, jpeg, webp	Imagem da etiqueta	Pré-visualização em telas e e-mails
pdf	Documento com uma página por etiqueta	Impressoras comuns e arquivamento
json	Etiquetas em Base64 dentro de um JSON	Pré-visualização no frontend
base64	Imagem codificada em Base64	Gravação em banco ou envio por API

curl -X POST https://zpl.diegobittencourt.dev.br/api/render/pdf \
  -H "Content-Type: application/json" \
  -d '{"zpl":"^XA^FO40,40^A0N,36,36^FDTeste^FS^XZ","widthMm":101.6,"heightMm":152.4,"dpmm":8}' \
  --output etiqueta.pdf

Quando o ZPL contém várias etiquetas, o PDF sai com uma página para cada uma. Nos formatos de imagem, o parâmetro page escolhe qual etiqueta renderizar. A especificação completa está publicada em /openapi.json, o que facilita a integração com outros sistemas e com ferramentas de IA.

Casos de uso no dia a dia

• Conferir a etiqueta de uma transportadora antes de imprimir um lote inteiro.
• Converter ZPL em PDF para impressoras que não entendem ZPL.
• Anexar a imagem da etiqueta ao pedido para consulta do atendimento.
• Testar novos modelos de etiqueta de produto sem gastar material.
• Validar automaticamente se um template gera a etiqueta esperada após uma mudança no sistema.

Perguntas frequentes

A pré-visualização é idêntica à impressão?

Ela é muito próxima, mas fontes internas e ajustes específicos de cada modelo de impressora podem gerar pequenas diferenças. Para etiquetas críticas, vale imprimir um teste final.

Qual densidade devo usar?

Use a mesma da impressora que vai imprimir. A maioria das impressoras de expedição trabalha com 203 dpi, ou 8 dpmm.

Posso converter várias etiquetas de uma vez?

Sim. No formato PDF, cada etiqueta do ZPL vira uma página do documento.

A API exige cadastro?

Não. O playground e a API estão abertos em zpl.diegobittencourt.dev.br. Para uso em alto volume ou uma instância dedicada para a sua empresa, entre em contato.