convertajá

Guia 10 de 10

Etiquetas ZPL pela API: ZPL para PDF e PDF para ZPL

Marketplaces e transportadoras entregam etiquetas em ZPL; quem não tem Zebra precisa de PDF. Quem tem Zebra recebe PDF e precisa de ZPL. As duas conversões agora rodam no servidor, com o mesmo motor da ferramenta do site.

8 min · Iniciante · atualizado em 17/10/2026

O que você vai construir

Um conversor de etiquetas para a expedição: ZPL do marketplace vira PDF 10×15 para qualquer impressora, e a etiqueta em PDF da transportadora vira ZPL enviado direto para a Zebra na rede.

Antes de começar

  • Uma chave de API em CONVERTAJA_KEY (veja Primeiros passos).
  • Um arquivo ZPL (.zpl, .txt ou .prn) ou uma etiqueta em PDF, PNG ou JPG.

Quanto custa

As duas ferramentas são leves: 1 crédito por arquivo enviado (o código ZPL mandado no campo zpl, sem arquivo, conta como 1). Um arquivo pode ter até 500 etiquetas (ZPL → PDF) ou 200 páginas (PDF → ZPL). Tarefa com erro devolve o crédito.

Passo 1: ZPL para PDF (ou PNG)

POST /v1/tools/zpl-para-pdf desenha cada etiqueta (^XA … ^XZ) numa página do tamanho certo. Envie arquivos no campo files ou o código na opção zpl:

OpçãoValores
width_mm, height_mmtamanho da etiqueta quando o ZPL não traz ^PW/^LL (padrão 100 × 150)
dpmm8 (203 dpi, padrão), 12 (300 dpi), 24 (600 dpi), 6 (152 dpi)
formatpdf (uma página por etiqueta, padrão) ou png (uma imagem por etiqueta)
use_label_sizetrue (padrão): usa ^PW/^LL do código quando existir
fittrue: encaixa no tamanho escolhido
copiestrue: repete a etiqueta conforme ^PQ
# Arquivo .zpl (ou .txt/.prn) → PDF com uma página por etiqueta, 10×15 cm a 203 dpi
curl -X POST "https://convertaja.com.br/v1/tools/zpl-para-pdf?wait=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "files=@etiquetas.zpl" \
  -F "width_mm=100" -F "height_mm=150" -F "dpmm=8"

# Ou o código direto no JSON (até 5 MB), com PNG em vez de PDF
curl -X POST "https://convertaja.com.br/v1/tools/zpl-para-pdf?wait=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"options":{"zpl":"^XA^FO50,50^A0N,50,50^FDPedido 1234^FS^FO50,130^BCN,100,Y^FD7891234567895^FS^XZ","format":"png"}}'
Resposta 200 (trecho)
{
  "id": "Q2n8c1ZpLx7d",
  "tool": "zpl-para-pdf",
  "operation": "zpl-pdf",
  "status": "done",
  "credits_charged": 1,
  "outputs": [
    {
      "index": 0,
      "name": "etiquetas.pdf",
      "size": 48213,
      "url": "https://convertaja.com.br/v1/jobs/Q2n8c1ZpLx7d/files/0"
    }
  ],
  "download_url": "https://convertaja.com.br/v1/jobs/Q2n8c1ZpLx7d/download",
  "info": "2 etiquetas · 10 × 15 cm · 203 dpi",
  "files_available": true
}

Dica Comandos que não mudam o desenho (configuração da impressora) são ignorados; os não suportados aparecem em info como "comandos ignorados". Suportamos texto (fonte 0 e bitmap), ^FB/^TB, caixas, círculos, linhas, ^GF/~DG, Code 128, Code 39, EAN/UPC, ITF, QR, DataMatrix, ^FR/^LR, ^FH, ^CI28 (UTF-8) e formatos ^DF/^XF.

Passo 2: PDF ou imagem para ZPL

POST /v1/tools/pdf-para-zpl desenha cada página no tamanho da etiqueta, passa para preto e branco e gera um ^GFA por página. O ZPL vem no arquivo .zpl e também em text (até 256 KB):

OpçãoValores
size100x150 (padrão), 100x100, 100x50, 60x40 ou page (tamanho da página)
dpmmresolução da impressora (padrão 8 = 203 dpi)
pagespáginas do PDF, ex.: 1-3,5 (vazio = todas)
rotate0, 90, 180 ou 270
thresholdlimiar de preto, 1 a 254 (padrão 128)
dithertrue para fotos e logos em tons de cinza
inverttrue inverte preto e branco
encodingascii (^GFA comprimido, padrão, funciona em todas) ou z64 (menor, firmware recente)
# Etiqueta em PDF (ou PNG/JPG) → ZPL com o desenho em ^GFA, pronto para a Zebra
curl -X POST "https://convertaja.com.br/v1/tools/pdf-para-zpl?wait=true" \
  -H "Authorization: Bearer $CONVERTAJA_KEY" \
  -F "files=@etiqueta-correios.pdf" \
  -F "size=100x150" -F "dpmm=8" -F "pages=1-2"
# A resposta traz o ZPL em "text" (até 256 KB) e o arquivo .zpl em outputs/download_url
Resposta 200 (trecho)
{
  "id": "h7Kp2mWq9sZt",
  "tool": "pdf-para-zpl",
  "operation": "pdf-zpl",
  "status": "done",
  "credits_charged": 1,
  "outputs": [
    {
      "index": 0,
      "name": "etiqueta-correios.zpl",
      "size": 17320,
      "url": "https://convertaja.com.br/v1/jobs/h7Kp2mWq9sZt/files/0"
    }
  ],
  "info": "1 etiqueta em ZPL (^GFA ASCII) · 203 dpi · 100 × 150 mm",
  "text": "^XA\n^PW800\n^LL1200\n^FO0,0^GFA,120000,120000,100,,::::…^FS\n^XZ\n"
}

Passo 3: Imprima

  • PDF: papel 100 × 150 mm e escala 100% (sem “ajustar à página”), para o código de barras sair no tamanho certo.
  • ZPL: mande o texto para a porta RAW 9100 da Zebra na rede (exemplo em Python acima) ou pelo driver “genérico/somente texto”. Use o mesmo dpmm da impressora: ZPL de 203 dpi numa Zebra de 300 dpi sai menor.

Atenção Etiquetas de transportadora têm código de barras: confira o primeiro lote lendo o código com um leitor antes de imprimir centenas.

Próximos passos

Todos os endpoints e opções: referência da API. Dúvidas? Fale com a gente e informe o X-Request-Id da chamada.