Resumo: um sistema hospedado na nuvem não consegue falar direto com a impressora USB ou de rede que está na expedição. A solução que desenvolvo é um agente local: um serviço do Windows que se registra no sistema, informa as impressoras disponíveis, busca os trabalhos pendentes e envia o ZPL em modo RAW para a impressora. A conexão é sempre de saída, sem abrir portas no firewall, e um registro local impede que a mesma etiqueta seja impressa duas vezes.
Neste artigo
O problema da impressão em sistemas web
Quando o sistema roda no navegador, a impressão normalmente passa pela janela de impressão do sistema operacional. Para documentos comuns isso funciona. Para etiquetas térmicas, não:
- O navegador converte a página em imagem e perde a precisão da etiqueta.
- O operador precisa escolher impressora, tamanho e margens a cada impressão.
- Etiquetas em ZPL, como as devolvidas pelas transportadoras, precisam chegar à impressora sem conversão.
- Em operações com volume, cada clique a mais vira minutos perdidos no fim do dia.
- O servidor na nuvem não tem acesso à rede interna da empresa.
A arquitetura: sistema, fila e agente
A solução tem duas partes. No sistema de gestão, um módulo de impressão local cadastra os terminais (computadores da operação), as impressoras de cada terminal, as impressoras padrão por usuário e a fila de trabalhos, com a origem de cada impressão. No computador da expedição, o agente roda como serviço do Windows e conversa com o sistema por HTTPS.
| Rota do sistema | Método | Função |
|---|---|---|
/local-printer/api/register | POST | Registro do terminal com nome, IP e impressoras; devolve um token |
/local-printer/api/heartbeat | POST | Sinal de vida periódico com a lista atualizada de impressoras |
/local-printer/api/jobs | GET | Lista os trabalhos pendentes daquele terminal |
/local-printer/api/job-done | POST | Confirma o resultado de cada trabalho: sucesso ou erro |
- Na instalação, o agente se registra e recebe um token próprio do terminal.
- A cada ciclo, que pode ir de 1 a 300 segundos, envia o heartbeat com as impressoras instaladas.
- Busca os trabalhos pendentes destinados àquele terminal.
- Envia o ZPL de cada trabalho para o spooler do Windows em modo RAW, direto para a impressora indicada.
- Confirma ao sistema o resultado de cada trabalho.
- No sistema, o usuário vê se o terminal está online e acompanha a fila.
Sem portas abertas no firewall
O agente sempre inicia a conexão, de dentro para fora, como um navegador faria. O sistema nunca precisa acessar a rede interna da empresa. Isso simplifica a implantação e reduz a superfície de ataque.
Resiliência: o que acontece quando algo falha
Na expedição, uma falha de impressão vira pacote parado. Por isso o agente foi desenhado para nunca travar o lote inteiro por causa de um problema isolado:
| Situação | Comportamento do agente |
|---|---|
| Servidor indisponível no registro | Tenta novamente nos próximos ciclos, sem travar o serviço |
| Falha temporária de rede | Retentativas com limite em heartbeat, busca e confirmação |
| Token rejeitado pelo servidor | Limpa o token e se registra de novo no ciclo seguinte |
| Um trabalho com erro | Registra a falha e continua com os próximos |
| Etiqueta impressa, mas confirmação falhou | Não imprime de novo: reenvia apenas a confirmação |
| Falha inesperada no serviço | O Windows reinicia o serviço automaticamente |
O ponto mais importante é a proteção contra etiqueta duplicada. O agente mantém um histórico local dos últimos trabalhos processados. Se o mesmo trabalho voltar da fila porque a confirmação não chegou ao servidor, ele reconhece o identificador e apenas reenvia a confirmação.
Operação e diagnóstico
Para o suporte, o agente mantém logs diários com retenção de 30 dias, um arquivo com o estado atual e um pequeno servidor local com as rotas /status e /health. Assim é possível conferir, no próprio computador da operação, se o agente está online, quais impressoras ele enxerga e qual foi o último erro, sem acessar o servidor.
Onde isso se encaixa na operação
- Expedição: a etiqueta da transportadora, gerada pela integração de frete, sai na impressora certa assim que o pedido é despachado.
- Produção e estoque: etiquetas de produto, lote e volume impressas a partir do apontamento.
- Vários galpões: cada terminal tem suas impressoras, e o sistema direciona o trabalho para o local correto.
- Pré-visualização: o mesmo ZPL pode ser conferido como imagem ou PDF no db ZPL antes de ir para a impressora.
Perguntas frequentes
Funciona com qualquer impressora térmica?
Funciona com impressoras que aceitam ZPL e estão instaladas no Windows, como as da linha Zebra e modelos compatíveis. O agente envia o conteúdo em modo RAW, sem conversão.
Preciso abrir alguma porta no firewall?
Não. O agente só faz conexões de saída por HTTPS, como um navegador.
E se a internet cair durante a expedição?
Os trabalhos continuam na fila do sistema. Quando a conexão volta, o agente busca os pendentes e imprime normalmente, sem duplicar o que já foi impresso.
Dá para imprimir em mais de um computador?
Sim. Cada computador roda seu agente e aparece como um terminal com suas próprias impressoras. O sistema escolhe o destino de cada trabalho.
Quer imprimir etiquetas direto do seu sistema?
Desenvolvo integrações de impressão local para expedição e produção, com fila de trabalhos, agente Windows, monitoramento dos terminais e etiquetas ZPL geradas a partir do ERP e das transportadoras.