Preciso de driver da Zebra para imprimir ZPL pelo Tagu?

Não necessariamente. O agente manda o ZPL direto para a impressora pela USB, pelo driver do Windows ou pela rede na porta 9100.

Qual o tamanho máximo de um trabalho?

O corpo da requisição aceita até 16 MB. Para arquivos maiores, use content_url para o Tagu buscar o conteúdo.

Como imprimir etiqueta ZPL pela API

Seu sistema gera o ZPL da etiqueta, faz um POST na API do Tagu e a etiqueta sai na Zebra da bancada, sem janela de impressão e sem ninguém abrir arquivo. Este guia mostra o caminho completo, do cadastro ao status do trabalho.

O que é ZPL

ZPL (Zebra Programming Language) é a linguagem que as impressoras térmicas da Zebra entendem. Uma etiqueta é um texto que começa em ^XA e termina em ^XZ, com comandos de posição, fonte e código de barras no meio:

etiqueta.zpl

^XA
^FO50,50^ADN,36,20^FDPED-48213^FS
^FO50,110^BCN,80,Y,N,N^FD7891234567895^FS
^XZ

Como a impressora recebe o texto pronto, a etiqueta sai rápida e sempre igual, sem depender de driver, escala ou margem de PDF. Elgin, Argox e TSC também aceitam ZPL na maioria dos modelos.

Antes do primeiro envio

Crie a conta. São 14 dias de teste grátis, sem cartão.
Instale o agente na bancada que tem a impressora (tagu-setup.exe, Windows 10 ou 11) e aprove o código que ele mostra no painel.
Marque as impressoras que a bancada vai usar. Cada uma ganha um id.
Em Chaves de API, crie uma chave para o seu sistema. Ela começa com tg_live_ e aparece uma vez só: guarde num cofre ou variável de ambiente.

Descubra o id da impressora

O id está no painel, no menu de cada impressora (Copiar id). Pelo código, liste as impressoras da conta. Use uma do tipo zpl:

GET /v1/printers

curl https://api.tagu.com.br/v1/printers \
  -H "Authorization: Bearer tg_live_..."

[
  { "id": "8f2c4b1e-...", "name": "Zebra expedição", "kind": "zpl", "state": "idle", ... },
  { "id": "a71d09c3-...", "name": "Laser balcão", "kind": "pdf", "state": "idle", ... }
]

Mande a etiqueta

O ZPL vai em content, codificado em base64. Se ele estiver num endereço público ou assinado, use content_url e o Tagu busca o arquivo.

POST /v1/jobs

curl -X POST https://api.tagu.com.br/v1/jobs \
  -H "Authorization: Bearer tg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "printer_id": "8f2c4b1e-...",
    "format": "zpl",
    "content": "XlhBXkZPNTAsNTBeQUROLDM2LDIwXkZEUEVELTQ4MjEzXkZTXlha",
    "copies": 1,
    "external_ref": "PED-48213",
    "idempotency_key": "PED-48213"
  }'

A resposta é 202 com o id do trabalho e o status queued. Em segundos a bancada recebe e imprime. Só printer_id e o conteúdo são obrigatórios; copies vai de 1 a 100.

Evite etiqueta duplicada

Rede instável faz o sistema repetir a chamada sem saber se a primeira chegou. Mande uma idempotency_key por etiqueta (o número do pedido serve). O segundo envio com a mesma chave devolve o trabalho que já existe, e nada sai repetido. O external_ref guarda o seu número de pedido para achar o trabalho depois no painel.

Acompanhe o status

O trabalho passa por queued, sent, printing e termina em done, failed ou canceled. Consulte quando precisar:

GET /v1/jobs/{id}

curl https://api.tagu.com.br/v1/jobs/c41e7a90-... \
  -H "Authorization: Bearer tg_live_..."

{ "id": "c41e7a90-...", "status": "done", "external_ref": "PED-48213", ... }

Acabou o papel ou a impressora desligou? O agente tenta de novo e mostra o motivo na bandeja e no painel. Se a internet cair, o que já chegou à bancada imprime assim mesmo, e o resto espera na nuvem.

Perguntas frequentes

Preciso de driver da Zebra para imprimir ZPL pelo Tagu?: Não necessariamente. O agente manda o ZPL direto para a impressora pela USB, pelo driver do Windows ou pela rede na porta 9100.
Qual o tamanho máximo de um trabalho?: O corpo da requisição aceita até 16 MB. Para arquivos maiores, use content_url para o Tagu buscar o conteúdo.