Tutorial de ZPL: comandos e exemplos

Este tutorial de ZPL cobre os poucos comandos por trás de toda etiqueta Zebra: ^XA e ^XZ para começar e terminar, ^FO para posicionar um campo, ^A0 para escolher a fonte, ^FD e ^FS para os dados, e ^BC e ^BQ para códigos de barras. Cada um vem com um exemplo que você pode colar num visualizador.

• Bom paraLer um ZPL que você herdou, depurar uma etiqueta ou mandar etiquetas a partir de um backend.
• Você precisa deNada para imprimir. O criador de etiquetas grátis escreve o ZPL para você.
• Bom saberO ZPL conta em pontos, então o mesmo código imprime diferente em cada DPI.

O que é ZPL

Toda etiqueta que uma Zebra imprime é um pequeno programa em ZPL, a Zebra Programming Language.

A impressora não aceita PDF nem arquivos do Word. Ela recebe comandos ZPL, um depois do outro, até chegar a um marcador que diz que a etiqueta acabou. Aí a cabeça de impressão dispara.

Você não precisa aprender ZPL para imprimir. O criador de etiquetas grátis escreve o código para você. Mesmo assim, o básico ajuda, por dois motivos:

• Quando algo dá errado (um código de barras borrado, texto cortado, um campo faltando), normalmente dá para rastrear até um comando específico.
• Se você monta qualquer automação no backend, como uma fila de impressão, uma integração com ERP ou um script de expedição, uma hora vai copiar ZPL de um editor e mandar pelo seu próprio código. Ajuda saber o que tem nessa string.

No fim, você vai conseguir olhar uma string ZPL e ter uma ideia da etiqueta que ela gera. A última parte mostra como funciona o Copy ZPL, para você encaixar no seu próprio fluxo.

A estrutura de uma etiqueta ZPL

A etiqueta ZPL mais simples possível é assim:

// Start a label
^XA

// Move to position (50, 50) and print "Hello World"
^FO50,50^A0N,36,36^FDHello World^FS

// End the label, fire the printer
^XZ

Toda etiqueta, por mais complexa que seja, começa com ^XA e termina com ^XZ. Tudo no meio é uma sequência de comandos.

Cada comando é um acento circunflexo (^) e duas letras que dão o nome, mais parâmetros opcionais separados por vírgulas.

O exemplo usa o mínimo:

• ^FO50,50 é o Field Origin. Ele define a posição do próximo elemento, em pontos a partir do canto superior esquerdo. Então 50,50 quer dizer 50 pontos para a direita e 50 para baixo.
• ^A0N,36,36 escolhe uma fonte interna: fonte 0, sem rotação, 36 pontos de altura e 36 de largura. Pense nele como o seletor de fonte e tamanho.
• ^FD é o Field Data, seguido do texto que você quer imprimir. ^FS, o Field Separator, fecha o campo.

Pontos, DPI e por que as coordenadas parecem estranhas

Todas as coordenadas e tamanhos em ZPL são em pontos, a resolução física da cabeça de impressão. Três faixas de DPI cobrem quase tudo:

• 203 DPI: 1 polegada tem 203 pontos. Uma etiqueta de 4 polegadas tem 812 pontos de largura.
• 300 DPI: 1 polegada tem 300 pontos. Uma etiqueta de 4 polegadas tem 1.200 pontos de largura.
• 600 DPI: 1 polegada tem 600 pontos. Uma etiqueta de 4 polegadas tem 2.400 pontos de largura.

Parece detalhe, mas muda a impressão. A mesma string ZPL cai em lugares diferentes em impressoras com DPI diferente.

Um ^FO100,100 numa impressora de 203 DPI coloca o campo a cerca de meia polegada da borda. Numa de 600 DPI, o mesmo comando coloca a cerca de 0.17 polegada. O ZPL não faz ideia do que é uma polegada. Tudo é ponto.

É por isso que o mylabelmaker acompanha o DPI da impressora ativa e renderiza na resolução nativa dela. Por que a sua Zebra imprime borrado em 300 DPI conta a história completa.

Os comandos ZPL que você mais vai ver

Só com esses você escreve uma etiqueta completa à mão. Uma etiqueta de produto pequena, com nome, preço e código de barras, tem umas dez linhas.

Cole um trabalho curto e veja o ZPL no navegador para conferir ^FO, ^A, ^BC ou ^BQ antes de imprimir.

Um exemplo de ZPL, linha por linha

Aqui vai uma etiqueta mais completa, do tipo que o mylabelmaker gera quando você cria uma etiqueta de envio:

^XA
^MD12
^PR4
^PW812
^PQ1
^FO0,0
^GFA,121800,121800,150,[hex bitmap data omitted]^FS
^XZ

• ^XA começa a etiqueta.
• ^MD12 define o escurecimento (darkness) em 12, um valor intermediário sensato para um ribbon novo.
• ^PR4 imprime a 4 polegadas por segundo.
• ^PW812 define a largura de impressão em 812 pontos, que são 4 polegadas a 203 DPI.
• ^PQ1 imprime 1 cópia.
• ^FO0,0 coloca o próximo campo no canto superior esquerdo.
• ^GFA,121800,121800,150,… embute um bitmap de 121.800 bytes, com 150 bytes por linha, como a etiqueta inteira.
• ^FS fecha o campo.
• ^XZ manda a impressora imprimir.

Esse ^GFA é o jeito padrão do mylabelmaker. Ele renderiza a área de edição inteira (texto, códigos de barras, QR, formas, imagens) num único bitmap no DPI nativo da impressora e manda tudo como um só campo gráfico.

É o jeito mais confiável de fazer a etiqueta impressa ficar igual à tela, porque ele pula a renderização de fontes da própria impressora, a geração de códigos de barras e qualquer peculiaridade do firmware.

Tire o ZPL do mylabelmaker

Você não precisa escrever nada disso. O editor gera o ZPL de tudo o que você criar. Para pegar o código:

1. Abra https://app.mylabelmaker.com. Sem cadastro.
2. Escolha um tamanho e coloque texto, códigos de barras, QR codes ou imagens, o que a etiqueta precisar.
3. Abra as configurações da impressora (o ícone de engrenagem) e use Auto-detect (detecção automática), para a etiqueta renderizar no DPI real da sua impressora.
4. Clique em Options no canto superior direito do editor e depois em Copy ZPL (copiar ZPL). A string completa ^XA … ^XZ da etiqueta atual vai para a área de transferência.
5. Cole onde precisar: um arquivo de texto, um servidor de impressão, uma requisição para a sua API de expedição, uma mensagem de chat.

Variáveis e impressão em lote

Quando você imprime em lote a partir de um CSV ou de uma planilha do Google, o mylabelmaker gera uma string ZPL separada para cada linha, com os valores daquela linha preenchidos, e manda uma depois da outra.

O Copy ZPL copia só a linha atual. Isso é útil para testar uma linha no seu backend antes de soltar a planilha inteira.

Mande ZPL pelo seu próprio código

Com a string em mãos, o seu backend pode mandá-la para uma Zebra por um socket TCP (porta 9100 nas impressoras de rede), pela API em localhost do auxiliar Browser Print ou por qualquer servidor de impressão Zebra.

O exemplo mais simples, uma ZD621 conectada à rede em 192.168.1.50:

# Python
import socket
zpl = "^XA^FO50,50^A0N,36,36^FDHello^FS^XZ"
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(("192.168.1.50", 9100))
s.send(zpl.encode("utf-8"))
s.close()

Esse é o padrão inteiro. Em qualquer linguagem: abra um socket TCP para o IP da impressora na porta 9100, escreva os bytes do ZPL e feche. A impressora dispara assim que vê o ^XZ.

A lista curta para bater o olho num ZPL

Se você está lendo um ZPL que outra pessoa gerou, de um desenvolvedor anterior ou de um sistema que você herdou, estes são os que você vai encontrar:

Todo o resto é uma variação desses, ou um comando específico para coisas como gravação RFID, consultas de status ou configuração da impressora. A referência oficial do ZPL II, um PDF grátis da Zebra, traz a versão completa se você precisar.

Resumindo

O ZPL é uma linguagem de comandos pequena, em ASCII simples, que existe desde os anos 1990 e não dá sinal de que vai sumir.

Você não precisa escrever ZPL. O editor cuida das peculiaridades (conversão de DPI, rasterização de fontes, codificação de códigos de barras, empacotamento do bitmap) e manda uma string ^XA … ^XZ limpa para a sua impressora.

Você não precisa escrever ZPL, mas saber o que tem na string faz você depurar melhor.

Também ajuda quando você conecta um backend, ou quando alguém pergunta o que o software de etiquetas está fazendo de fato.