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.
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ção | Valores |
|---|---|
width_mm, height_mm | tamanho da etiqueta quando o ZPL não traz ^PW/^LL (padrão 100 × 150) |
dpmm | 8 (203 dpi, padrão), 12 (300 dpi), 24 (600 dpi), 6 (152 dpi) |
format | pdf (uma página por etiqueta, padrão) ou png (uma imagem por etiqueta) |
use_label_size | true (padrão): usa ^PW/^LL do código quando existir |
fit | true: encaixa no tamanho escolhido |
copies | true: 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"}}'import { readFile, writeFile } from 'node:fs/promises';
const auth = { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` };
const zpl = await readFile('etiquetas.zpl', 'utf8'); // ZPL gerado pelo marketplace, transportadora ou ERP
const res = await fetch('https://convertaja.com.br/v1/tools/zpl-para-pdf?wait=true', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ options: { zpl, width_mm: 100, height_mm: 150, dpmm: '8', format: 'pdf' } }),
});
const tarefa = await res.json();
if (!res.ok) throw new Error(`${tarefa.error.code}: ${tarefa.error.message}`);
if (tarefa.status !== 'done') throw new Error(tarefa.error ? tarefa.error.message : `tarefa ${tarefa.id} ainda em andamento`);
console.log(tarefa.info); // ex.: 2 etiquetas · 10 × 15 cm · 203 dpi
const pdf = await fetch(tarefa.download_url, { headers: auth });
await writeFile('etiquetas.pdf', Buffer.from(await pdf.arrayBuffer()));import os
import requests
auth = {"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"}
with open("etiquetas.zpl", "rb") as f:
res = requests.post(
"https://convertaja.com.br/v1/tools/zpl-para-pdf",
params={"wait": "true"},
headers=auth,
files={"files": f},
data={"width_mm": "100", "height_mm": "150", "dpmm": "8", "format": "pdf"},
timeout=90,
)
tarefa = res.json()
if not res.ok:
raise SystemExit(f"{tarefa['error']['code']}: {tarefa['error']['message']}")
if tarefa["status"] != "done":
raise SystemExit(tarefa.get("error", {}).get("message", "ainda em andamento"))
print(tarefa["info"])
open("etiquetas.pdf", "wb").write(requests.get(tarefa["download_url"], headers=auth, timeout=60).content)
{
"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ção | Valores |
|---|---|
size | 100x150 (padrão), 100x100, 100x50, 60x40 ou page (tamanho da página) |
dpmm | resolução da impressora (padrão 8 = 203 dpi) |
pages | páginas do PDF, ex.: 1-3,5 (vazio = todas) |
rotate | 0, 90, 180 ou 270 |
threshold | limiar de preto, 1 a 254 (padrão 128) |
dither | true para fotos e logos em tons de cinza |
invert | true inverte preto e branco |
encoding | ascii (^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_urlimport { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';
const form = new FormData();
form.append('files', await openAsBlob('etiqueta-correios.pdf'), 'etiqueta-correios.pdf');
form.append('options', JSON.stringify({ size: '100x150', dpmm: '8', threshold: 128, encoding: 'ascii' }));
const res = await fetch('https://convertaja.com.br/v1/tools/pdf-para-zpl?wait=true', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` },
body: form,
});
const tarefa = await res.json();
if (!res.ok) throw new Error(`${tarefa.error.code}: ${tarefa.error.message}`);
if (tarefa.status !== 'done') throw new Error(tarefa.error ? tarefa.error.message : 'ainda em andamento');
console.log(tarefa.info); // ex.: 1 etiqueta em ZPL (^GFA ASCII) · 203 dpi · 100 × 150 mm
await writeFile('etiqueta.zpl', tarefa.text);import os
import socket
import requests
with open("etiqueta-correios.pdf", "rb") as f:
res = requests.post(
"https://convertaja.com.br/v1/tools/pdf-para-zpl",
params={"wait": "true"},
headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"},
files={"files": f},
data={"size": "100x150", "dpmm": "8", "dither": "false"},
timeout=90,
)
tarefa = res.json()
if not res.ok or tarefa["status"] != "done":
raise SystemExit(tarefa.get("error", {}).get("message", "falhou"))
zpl = tarefa["text"]
open("etiqueta.zpl", "w").write(zpl)
# Opcional: manda direto para a Zebra na rede (porta RAW 9100)
IMPRESSORA = os.environ.get("ZEBRA_IP")
if IMPRESSORA:
with socket.create_connection((IMPRESSORA, 9100), timeout=10) as s:
s.sendall(zpl.encode("ascii"))
{
"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
dpmmda 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.