Agente de Impressão

Aplicativo que roda no computador da loja e imprime as comandas automaticamente. Ele conversa com o sistema pela internet (não precisa abrir portas nem configurar roteador) e manda os pedidos direto para a impressora térmica — substitui o QZ Tray.

Onde cada coisa roda: o site/sistema fica hospedado na nuvem; este app fica no PC da loja. Você recebe este programa em um .zip, instala na estação e conecta.

---

1. Requisitos

• Windows 10 ou 11.
• A impressora térmica ligada e:
  • instalada no Windows (USB ou rede já adicionada em Configurações → Impressoras), ou
  • de rede com IP fixo (aceita conexão na porta 9100).
• Internet no computador (a mesma que abre o painel do site).

---

2. Instalar

1. Descompacte o .zip que você recebeu.
2. Execute o instalador Agente de Impressao Setup <versão>.exe (ou, na versão portátil, AgenteImpressao-portatil-<versão>.exe, que roda sem instalar). O <versão> é um número, ex.: 1.0.0.
3. Na primeira vez o Windows pode pedir confirmação (SmartScreen) → Mais informações → Executar assim mesmo.
4. O app abre a janela de configuração e fica com um ícone na bandeja (ao lado do relógio; pode estar na setinha “mostrar ícones ocultos” ^). Fechar a janela não fecha o app — ele continua rodando na bandeja. Para reabrir a janela, dê duplo-clique no ícone da bandeja.

---

3. Configurar e conectar (primeira vez)

Siga na ordem, na janela do app:

Passo 1 — Servidor

No campo Servidor, cole o endereço do sistema (o administrador te passa, ex.: https://seusite.discloud.app) e clique Salvar.

Passo 2 — Parear com a loja

1. No painel do site, entre em Impressão → Gerar código de pareamento. Vai aparecer um código como ABCD-2345 (vale ~10 minutos).
2. No app, digite esse código, dê um nome para a estação (ex.: “Caixa” ou “Cozinha”) e clique Parear.
3. O status no topo deve virar Conectado (verde).

Passo 3 — Conferir as impressoras

Na seção Impressoras aparecem as impressoras do Windows automaticamente. Clique Testar na sua impressora para sair um cupom de teste.

• Se a sua térmica for de rede por IP e não aparecer na lista, abra “Adicionar impressora de rede (IP:9100)”, informe nome e IP e clique Adicionar. Depois clique Testar.

Passo 4 — Definir função/vias (no painel do site)

Quem imprime o quê (Cozinha / Caixa / Expedição), o número de vias e o auto-imprimir são configurados no painel do site, na tela de Impressão — as impressoras desta estação já aparecem lá para você escolher.

Passo 5 — Iniciar com o Windows

A opção “Iniciar automaticamente com o Windows” já vem ligada. Confirme que ela está marcada na seção Opções.

Instalação pela pasta (sem instalador)? Se você recebeu a pasta do agente em vez do instalador, dê duplo clique em INSTALAR-INICIO-AUTOMATICO.cmd (na pasta do agente). Ele cria o atalho na inicialização do Windows apontando para o app. Para desfazer: powershell -ExecutionPolicy Bypass -File scripts\inicio-automatico.ps1 -Remover.

Se a janela mostrar o aviso “o Windows não confirmou o registro”, é exatamente esse .cmd que resolve.

Pronto. A partir daí, cada novo pedido imprime sozinho.

---

4. No dia a dia

• Deixe o computador ligado com o app na bandeja. O status Conectado indica que está tudo certo.
• Caiu a internet ou o PC estava desligado? O status vira Offline e o app reconecta sozinho quando voltar. As comandas dos pedidos que entraram nesse período ficam guardadas no servidor e saem assim que a estação conecta (sem duplicar). Depois de 90 minutos parada, a comanda deixa de sair sozinha e passa a aparecer como falha no painel, com botão Reenviar — evita a loja acordar imprimindo pedidos da madrugada.
• Falhou a impressão? (papel acabou, impressora desligada) aparece um aviso do Windows na hora e o motivo fica no painel, em Impressão → Diagnóstico e fila.
• Reimprimir um pedido: pelo painel do site (tela de Impressão).
• Atualizações: o app verifica sozinho se há versão nova (ao abrir e a cada 6h) e avisa com uma faixa azul na janela. O botão Baixar abre o link da versão nova.

---

5. Problemas comuns

Sintoma	O que fazer
Status Não pareado	Faça o Passo 2 (gerar código no painel e parear).
Status Não autorizado	O dispositivo foi revogado no painel. Clique Desparear e pareie de novo com um código novo.
Status Offline	Verifique a internet do PC. O app reconecta sozinho. Se quiser, clique Reconectar.
Pedido entrou e a comanda não saiu	Abra o painel em Impressão → Diagnóstico e fila: ele diz a causa (estação offline, nenhuma impressora com “Auto”, impressora apontando para estação removida, ou falha da impressora).
Não abriu sozinho ao ligar o PC	Marque a opção em Opções e rode INSTALAR-INICIO-AUTOMATICO.cmd. Confirme depois em Gerenciador de Tarefas → Inicializar.
Testar falha (Windows)	Confirme o nome exato da impressora em Configurações → Impressoras e se ela está online/com papel.
Testar falha (rede)	Confira o IP e se a impressora aceita a porta 9100. Teste o IP na mesma rede.
Sai “papel picado”/símbolos	A impressora precisa aceitar ESC/POS RAW (a maioria das térmicas aceita). Impressoras comuns (jato/laser) não servem.
Ver detalhes técnicos	Botão Abrir registro (log) — mostra erros recentes (sem dados de cliente).

---

6. Para quem prepara o pacote (build) — técnico

O app é Electron. Para gerar o instalador/portátil localmente:

npm install
npm run dist        # gera instalador NSIS + portátil em dist/
# ou:
npm run pack        # só empacota (sem instalador), para testar rápido

Rodar em desenvolvimento (sem empacotar):

npm install
npm start

Publicar uma versão nova

O build oficial sai do GitHub Actions (.github/workflows/release-agent.yml), que compila no Windows e publica na Release — é de lá que as estações se atualizam:

# 1) suba a versão em package.json (ex.: 1.2.0), commit
git tag v1.2.0
git push origin v1.2.0
# 2) o workflow gera o instalador e PUBLICA a Release
# 3) aponte o servidor para a nova versão:
#    PRINTER_AGENT_VERSION / PRINTER_AGENT_DOWNLOAD_URL no .env

O passo 3 é o que controla o rollout: enquanto o servidor não anunciar a versão, as estações não são avisadas — dá para atualizar uma loja de cada vez.

Notas:

• Este repositório é público de propósito: o electron-updater baixa o instalador da Release sem precisar de um token embutido no app instalado nas lojas.
• O app é white-label: não há endereço de servidor, marca ou credencial no código — a identidade vem do pareamento e o servidor é digitado na tela de configuração.
• O endereço do servidor é configurável no app. Se um dia quiser embutir um padrão, dá para pré-preencher serverUrl.
• Transportes suportados: TCP 9100 (rede) e spooler RAW do Windows (via scripts/rawprint.ps1, que precisa ir unpacked no build — já configurado em package.json → build.asarUnpack).
• Config e log ficam em %APPDATA%\agente-impressao\ (config.json, agent.log).