Referência ZPL: Linguagem de Programação, Fontes e Formato
O manual completo da Zebra Programming Language — anatomia, comandos, fontes, códigos de barras e exemplos prontos para copiar e colar em envios, varejo e logística.
TL;DR
ZPL (Zebra Programming Language) é o padrão de fato para impressão de etiquetas térmicas desde os anos 80. Toda etiqueta começa com ^XA e termina com ^XZ. Comandos com ^ entram no formato; comandos com ~ configuram a impressora. As coordenadas usam dots (203 dpi = 8 dots/mm, 300 dpi = 12 dots/mm). As fontes integradas 0 e A–H cobrem a maioria dos casos — a Fonte 0 é totalmente escalável. Os códigos de barras mais usados são ^BC (Code 128) para envios, ^BQ (QR) para rastreio e ^BE (EAN-13) para varejo. Defina a posição do campo com ^FO, escreva o dado com ^FD e feche cada campo com ^FS. Use ^CI28 para habilitar UTF-8 e caracteres internacionais.
Experimente nossas ferramentas ZPL gratuitas agora
Gratuito, sem cadastro — Resultados instantâneos
O que é ZPL (Zebra Programming Language)?
ZPL é a sigla de Zebra Programming Language, uma linguagem de descrição de página criada pela Zebra Technologies nos anos 80 para controlar impressoras térmicas de etiquetas. É o padrão da indústria para etiquetas de envio, identificação de armazém, tags de preço de varejo e embalagem farmacêutica, porque é compacta, determinística e suportada por todos os modelos de impressora Zebra (ZD, ZT, ZE, ZQ, GK, GX, ZM e as antigas 105SL/110XiIII).
Um programa ZPL é um fluxo de texto puro de comandos que a impressora interpreta linha a linha. Cada comando começa com um caractere de controle — ^ (caret) para comandos de formato ou ~ (til) para comandos de configuração — seguido de um código de dois caracteres e parâmetros opcionais separados por vírgulas. ZPL II, a revisão atual, adiciona gráficos, fontes baixáveis, campos fixos e serializados, etiquetas multi-formato e comunicação bidirecional. O mesmo código imprime o mesmo resultado em qualquer impressora Zebra, o que torna ZPL a língua franca da produção de etiquetas no mundo todo.
Anatomia do formato ZPL
Toda etiqueta imprimível é um bloco autocontido chamado formato. O formato abre com ^XA, contém um ou mais campos e fecha com ^XZ. Dentro do bloco, a ordem dos comandos importa: a impressora os aplica sequencialmente como estado. Um campo — texto, código de barras ou gráfico — é definido por um comando de posição (^FO ou ^FT), um comando de conteúdo (^A, ^BC, ^GB, etc.) e um separador (^FS). O que estiver fora de ^XA..^XZ é tratado como configuração e executado imediatamente.
- Toda etiqueta começa com ^XA e termina com ^XZ. O que estiver fora é configuração, não conteúdo imprimível.
- Comandos que começam com ^ são comandos de formato e vivem dentro do bloco ^XA..^XZ.
- Comandos que começam com ~ são comandos de controle que configuram a impressora e podem ser enviados isolados (ex.: ~JR reinicia a impressora).
- Cada campo imprimível deve fechar com ^FS (separador de campo). Esquecer ^FS é a causa mais comum de saída quebrada.
- Parâmetros são separados por vírgula e são posicionais. Parâmetros omitidos assumem o valor padrão da impressora ou o último valor definido.
- Use ^CI28 dentro do formato para habilitar UTF-8 e caracteres não-ASCII (acentos, ç, ã, é, ü, chinês, cirílico).
- Os comandos são sensíveis a maiúsculas. ^FO e ^fo não são equivalentes — sempre em maiúsculas.
- Espaços em branco e quebras de linha entre comandos são ignorados, então você pode formatar seu ZPL para legibilidade.
^XA ; Início do formato
^CI28 ; Habilita UTF-8
^CF0,40 ; Fonte 0 padrão, tamanho 40
^FO50,50 ; Posição X=50, Y=50
^FDOlá Mundo ZPL^FS ; Imprime texto, fecha campo
^FO50,120^BY3 ; Novo campo + largura do barcode
^BCN,100,Y,N,N ; Code 128, 100 dots de altura
^FD1234567890^FS ; Dados do barcode, fecha campo
^XZ ; Fim do formato → imprimeSistema de coordenadas e DPI
ZPL posiciona cada elemento usando coordenadas em dots medidas a partir do canto superior esquerdo da etiqueta. A conversão entre milímetros ou polegadas e dots depende da densidade de impressão (DPI). Saber a contagem exata de dots da sua etiqueta é essencial para alinhamento perfeito, especialmente em formulários pré-impressos e transportadoras como Correios, FedEx, UPS ou Mercado Livre, que impõem dimensões estritas.
- Impressoras de 203 dpi: 8 dots por mm (203 dots por polegada). Uma etiqueta de 4×6 polegadas = 812×1218 dots.
- Impressoras de 300 dpi: 12 dots por mm (300 dots por polegada). A mesma etiqueta de 4×6 = 1200×1800 dots.
- Impressoras de 600 dpi: 24 dots por mm. Usadas principalmente para tags de joalheria e varejo ultra-finos.
- ^FO x,y posiciona um campo pelo canto superior esquerdo de sua bounding box.
- ^FT x,y posiciona um campo pela linha base do texto — útil ao misturar tamanhos de fonte.
- Y cresce para baixo. ^FO0,0 é o canto superior esquerdo; ^FO0,1218 é o fundo de uma etiqueta de 6 polegadas a 203 dpi.
- Teste sempre em escala 100%; ferramentas de render podem redimensionar o preview, mas a impressora aplica os dots literalmente.
Guia de programação ZPL: do Hello World a uma etiqueta de envio
Três exemplos progressivamente mais ricos. Cole cada um no visualizador ZPL para ver exatamente o que sai pela impressora.
Passo 1 — Hello World
O programa ZPL válido mínimo. Abre um formato, imprime um único campo de texto em (50,50) usando a Fonte 0 escalável padrão a 40 dots de altura e fecha o formato.
^XA
^CF0,40
^FO50,50^FDHello ZPL^FS
^XZPasso 2 — Texto + código de barras Code 128
Adiciona um Code 128 (^BC), padrão para etiquetas de envio. ^BY define a largura do módulo antes de declarar o barcode. O barcode renderiza os dígitos legíveis abaixo graças ao flag Y.
^XA
^CF0,40
^FO50,50^FDPedido #1042^FS
^FO50,120^BY3
^BCN,100,Y,N,N
^FD1234567890^FS
^XZPasso 3 — Etiqueta de envio completa
Combina texto variável, um bloco multi-linha de endereço, um QR Code e um Code 128 de rastreio — a estrutura de uma etiqueta de envio real de e-commerce.
^XA
^CI28
^CF0,32
^FO40,40^FDEnviar para:^FS
^FO40,90^FB540,4,0,L,0^FDJoana Silva\&Rua das Flores, 123\&São Paulo, 01000-000\&Brasil^FS
^FO40,260^FDPedido #A-7782^FS
^FO40,310^BY3^BCN,90,Y,N,N^FD1Z999AA10123456784^FS
^FO450,260^BQN,2,5^FDQA,https://example.com/track/A-7782^FS
^XZReferência de comandos ZPL
Os comandos ZPL II mais usados agrupados por finalidade. Para cada comando listamos uma descrição curta, um exemplo que você pode colar em um visualizador e o significado dos parâmetros.
Formato e controle
| Comando | Descrição | Exemplo | Parâmetros |
|---|---|---|---|
| ^XA | Início do formato de etiqueta. Obrigatório no começo de toda etiqueta imprimível. | ^XA ... ^XZ | Nenhum |
| ^XZ | Fim do formato de etiqueta. Envia a etiqueta para a fila de impressão. | ^XA^FO50,50^FDOi^FS^XZ | Nenhum |
| ^FS | Separador de campo. Fecha o campo atual. Obrigatório após cada elemento imprimível. | ^FO50,50^FDTexto^FS | Nenhum |
| ^CI | Muda o conjunto internacional de caracteres. ^CI28 habilita UTF-8 para acentos e scripts não-latinos. | ^CI28 | 28 = UTF-8, 13 = Latin-1 |
| ^CF | Fonte, altura e largura padrão para toda a etiqueta. Evita repetir ^A por campo. | ^CF0,30,30 | fonte,altura,largura |
| ^LH | Label Home — desloca a origem (0,0) de todas as coordenadas. | ^LH30,30 | x,y em dots |
| ^PQ | Quantidade de impressão. Emite a mesma etiqueta N vezes após ^XZ. | ^PQ5,0,0,N | qtd,pausa,replicar,override |
| ~JR | Reset da impressora. Enviado fora de um formato; a impressora reinicia. | ~JR | Nenhum |
Posicionamento e texto
| Comando | Descrição | Exemplo | Parâmetros |
|---|---|---|---|
| ^FO | Origem do campo — posiciona o próximo campo pelo canto superior esquerdo. | ^FO50,80 | x,y em dots |
| ^FT | Field Typeset — posiciona o próximo campo pela linha base do texto. Bom para tamanhos mistos. | ^FT50,80 | x,y em dots |
| ^A | Seleção de fonte para o próximo campo. Sobrescreve ^CF localmente. | ^A0N,40,40 | fonte,orientação,altura,largura |
| ^FD | Dado do campo. O texto ou valor numérico literal a imprimir. | ^FDPedido #42^FS | texto (até 3072 chars) |
| ^FB | Bloco de campo — texto multi-linha com wrap e alinhamento. | ^FB400,3,0,L,0^FD…^FS | largura,maxLinhas,entrelinha,alinhamento,recuo |
| ^FN | Número de campo — placeholder de template preenchido depois com dado ^FN. | ^FN1^FS | 1–999 |
| ^SN | Número serial — auto-incrementa entre cópias num mesmo job de impressão. | ^SN001,1,Y | início,incremento,preencher-zeros |
Códigos de barras
| Comando | Descrição | Exemplo | Parâmetros |
|---|---|---|---|
| ^BY | Largura de módulo e razão padrão. Deve vir ANTES do comando de barcode. | ^BY3,3,100 | larguraMódulo,razão,altura |
| ^BC | Code 128 — o padrão em envios e logística. | ^BCN,100,Y,N,N | orientação,altura,linha-abaixo,linha-acima,checkDigit |
| ^BQ | QR Code — URLs, JSON, IDs de rastreio. Até 7089 chars numéricos. | ^BQN,2,5 | orientação,modelo,magnificação |
| ^BE | EAN-13 — código de produto retail global (13 dígitos). | ^BEN,100,Y,N | orientação,altura,linha-abaixo,linha-acima |
| ^BU | UPC-A — código de produto retail norte-americano (12 dígitos). | ^BUN,100,Y,N | orientação,altura,linha-abaixo,linha-acima |
| ^BX | Data Matrix — código 2D de alta densidade para itens pequenos e farma. | ^BXN,200,200 | orientação,altura,qualidade |
| ^B0 | Aztec — código 2D usado em tickets de transporte e SmartCard. | ^B0N,7,N,0,N | orientação,magnificação(1-10),ECI(Y/N),controleErro(0-300),menu(Y/N) |
| ^B7 | PDF417 — código 2D empilhado usado em carteiras de motorista e envios. | ^B7N,8,5,10,30,N | orientação,alturaLinha,segurança(0-8),cols(1-30),linhas(3-90),truncar(Y/N) |
Gráficos
| Comando | Descrição | Exemplo | Parâmetros |
|---|---|---|---|
| ^GB | Caixa gráfica — retângulos, bordas, separadores. | ^GB300,2,2,B^FS | largura,altura,espessura,cor |
| ^GC | Círculo gráfico. | ^GC100,3,B^FS | diâmetro,espessura,cor |
| ^GD | Linha diagonal. | ^GD200,200,2,B,R^FS | largura,altura,espessura,cor,orientação |
| ^GF | Campo gráfico — bitmap embutido (ASCII ou comprimido). | ^GFA,1024,1024,32,… | formato,bytes,total,bytesPorLinha,dados |
| ^FR | Field Reverse — inverte preto/branco dentro do campo. | ^FO50,50^FR^GB100,30,30^FS | Nenhum |
Fontes ZPL: integradas e escaláveis
As impressoras Zebra trazem um conjunto fixo de fontes bitmap (A até H) mais uma fonte totalmente escalável (0). A Fonte 0 é a única que pode ser definida em qualquer altura e largura via ^CF ou ^A; as bitmap têm tamanhos fixos que podem ser esticadas mas não redesenhadas nitidamente. O comando ^A seleciona fonte + tamanho para um único campo; ^CF define o padrão para toda a etiqueta.
| Código | Nome | Tamanho | Notas |
|---|---|---|---|
| 0 | Fonte 0 (CG Triumvirate) | Escalável, qualquer altura/largura | Fonte escalável padrão. Ideal para preços, títulos, conteúdo dinâmico. |
| A | Fonte A | 9 × 5 dots (fixa) | Menor bitmap. Ideal para letra miúda e etiquetas densas. |
| B | Fonte B | 11 × 7 dots (fixa) | Um pouco maior que A. Comum em itens de linha. |
| C / D | Fonte C, D | 18 × 10 dots (fixa) | Bitmaps de tamanho médio para campos variáveis. |
| E | Fonte E | 28 × 15 dots (OCR-B) | Amigável para leitura ótica. |
| F | Fonte F | 26 × 13 dots | Bitmap maior de uso geral. |
| G | Fonte G | 60 × 40 dots | Tamanho display, para cabeçalhos. |
| H | Fonte H (OCR-A) | 21 × 13 dots | Padrão OCR-A, desenhada para leitura por máquina. |
| P–V | Fontes soft P–V | Variável | Letras P, Q, R, S, T, U, V — fontes bitmap legadas em firmware antigo. |
^XA
^CF0,50,50 ; Fonte 0 padrão a 50x50
^FO50,50^FDPreço: R$ 19,99^FS
^FO50,120^ABN,30,15 ; Fonte B explícita
^FDSKU: ABC-001^FS
^FO50,170^A0N,80,80 ; Fonte 0 grande inline
^FDOFERTA^FS
^XZCódigos de barras em ZPL
ZPL renderiza nativamente toda simbologia 1D e 2D comum. Sempre declare ^BY (largura de módulo e razão) antes do comando de barcode para deixar os scanners felizes.
Code 128
^BCEnvios, logística, rastreio de pacotes. Números + letras. Padrão de Correios, FedEx, UPS.
^FO50,50^BY3^BCN,100,Y,N,N^FD1234567890^FSQR Code
^BQURLs, payloads JSON, IDs de rastreio. Até 7089 chars numéricos. Leitores universais.
^FO50,50^BQN,2,6^FDQA,https://zplpdf.com^FSEAN-13
^BEProdutos retail no mundo todo. Exatamente 12 dígitos — o 13º é checksum automático.
^FO50,50^BY2^BEN,100,Y,N^FD750123456789^FSUPC-A
^BUVarejo norte-americano. 11 dígitos + checksum automático.
^FO50,50^BY2^BUN,100,Y,N^FD01234567890^FSData Matrix
^BXUDI farmacêutico, eletrônica, itens muito pequenos. Lê em qualquer ângulo.
^FO50,50^BXN,200,200^FDPharmaCode-42^FSAztec
^B0Tickets de transporte, cartões de embarque. Compacto, sem zona de silêncio.
^FO50,50^B0N,7,N,0,N^FDBOARDING-A14^FSPDF417
^B7Carteiras de motorista, IDs, envios. 2D empilhado, até ~1.1 KB.
^FO50,50^B7N,8,5,10,30,N^FDLastName/FirstName/DOB^FSCode 39
^B3Inventário interno, tags de ativo. Alfanumérico, menos denso que Code 128.
^FO50,50^BY3^B3N,N,100,Y,N^FDASSET-001^FSExemplos ZPL completos (copiar e colar)
Programas funcionais prontos para colar no visualizador ZPLPDF. Cada exemplo é um bloco ^XA..^XZ testado a 203 dpi em etiqueta 4×6 polegadas.
Etiqueta de envio — pacote e-commerce
Remetente, destinatário, Code 128 de rastreio e QR para URL de tracking.
^XA
^CI28
^PW812
^LL1218
^CF0,28
^FO40,40^FDDE:^FS
^FO40,80^FB400,3,0,L,0^FDZPLPDF Centro de Distribuição\&Av. Logística 500\&São Paulo, 01000-000^FS
^FO40,210^FDPARA:^FS
^FO40,250^A0N,38,38^FB500,4,0,L,0^FDJoana Silva\&Rua das Flores 123\&São Paulo, 01000-000\&Brasil^FS
^FO40,520^GB720,2,2,B^FS
^FO40,540^FDRastreio:^FS
^FO40,580^BY3^BCN,110,Y,N,N^FD1Z999AA10123456784^FS
^FO520,540^BQN,2,6^FDQA,https://zplpdf.com/track/1Z999AA10123456784^FS
^FO40,820^FDPedido #A-7782^FS
^FO40,860^FD2026-05-21^FS
^XZTag de preço retail com EAN-13
Nome do produto, SKU, EAN-13 e preço destacado em caixa reverse-print.
^XA
^CI28
^CF0,40
^FO40,30^A0N,50,50^FDCafé Orgânico 250g^FS
^FO40,100^FDSKU: COF-ORG-250^FS
^FO40,150^BY2^BEN,100,Y,N^FD750123456789^FS
^FO40,290^GB300,80,80,B^FS
^FO50,300^FR^A0N,60,60^FDR$ 12,99^FS
^XZEtiqueta de farmácia com Data Matrix (GS1)
Nome do fármaco, lote e validade com Data Matrix carregando identificadores GS1 — habitual na cadeia farmacêutica.
^XA
^CI28
^CF0,32
^FO40,40^A0N,44,44^FDParacetamol 500 mg^FS
^FO40,100^FDLote: B25C-0481^FS
^FO40,150^FDVal: 2027-09^FS
^FO40,200^BXN,200,200^FD>;(01)07640123456789(17)270930(10)B25C-0481^FS
^XZLote serializado — 50 etiquetas únicas
^PQ50 imprime 50 cópias; ^SN auto-incrementa o número serial em cada uma.
^XA
^CF0,40
^FO50,50^FDLote SN^FS
^FO50,120^A0N,80,80^SN0001,1,Y^FS
^PQ50,0,0,N
^XZErros comuns em ZPL e como corrigir
A etiqueta sai em branco ou pula papel.
→ Falta ^XZ no final ou há caracteres extras entre ^XA e ^XZ.
✓ Garanta que o formato comece com ^XA, termine com ^XZ e que nenhum byte solto quebre o fluxo.
O texto mostra ? no lugar de acentos (á, ç, é).
→ A codificação padrão é CP-850 e não carrega bytes UTF-8.
✓ Adicione ^CI28 logo depois de ^XA para passar a impressora a UTF-8.
O barcode imprime mas o scanner não lê.
→ Largura de módulo pequena demais ou razão fora da spec.
✓ Defina ^BY3,3,100 antes do barcode e mantenha zonas de silêncio ao redor.
O campo aparece em posição errada.
→ Mistura de ^FO e ^FT — usam pontos de referência diferentes.
✓ Escolha um: ^FO (canto superior esquerdo) ou ^FT (linha base). Não alterne no meio da etiqueta.
O texto multi-linha extrapola o limite da etiqueta.
→ ^FD só faz wrap quando envolto em ^FB.
✓ Envolva o texto multi-linha em ^FBlargura,maxLinhas,entrelinha,alinhamento,recuo antes de ^FD.
A imagem (^GF) imprime corrompida.
→ Contagem de bytes ou bytes-por-linha não bate com o tamanho dos dados.
✓ Re-codifique a imagem com uma ferramenta conhecida — bytesPorLinha deve ser ceil(largura/8).
Referência ZPL — Perguntas frequentes
Para que serve ZPL?
ZPL é o mesmo que Zebra Programming Language?
Como aprendo ZPL rápido?
Qual comando ZPL define a fonte?
Como adiciono um QR Code em ZPL?
Como imprimo um Code 128?
Qual a diferença entre ^FO e ^FT?
Quantos DPI tem minha impressora Zebra?
Posso testar ZPL sem impressora?
ZPL é o mesmo que EPL?
Teste seu ZPL agora mesmo
Cole qualquer um dos exemplos desta página no nosso visualizador ZPL gratuito online para ver exatamente o que sua impressora vai produzir — sem cadastro, sem download.