Configuração da impressora de recibos: como conectar e imprimir pedidos

O Print Agent do RestaurantManage é um serviço leve do Windows que recebe comandos de impressão da nuvem e os envia para sua impressora térmica de recibos — permitindo a impressão automática de recibos quando os pedidos são pagos ou quando tickets de cozinha precisam ser impressos. O agente suporta impressoras de rede (TCP porta 9100), impressoras USB e conexões Windows Spooler. Este guia cobre instalação, configuração, conexão de impressoras e solução de problemas.

Como funciona a impressão de recibos?

O fluxo de impressão é totalmente automatizado. Quando um caixa confirma o pagamento ou um ticket de cozinha é acionado, o backend do RestaurantManage gera o recibo completo como comandos de bytes ESC/POS. Esses bytes são enviados por uma conexão WebSocket segura (PrintHub) para o Print Agent executando em um PC Windows no seu restaurante. O agente decodifica os dados e os encaminha diretamente para a impressora térmica conectada. Todo o processo leva menos de dois segundos, da confirmação do pagamento ao recibo impresso.

O pipeline de impressão completo

Entender o pipeline completo ajuda na solução de problemas. Esta é a sequência de eventos cada vez que um recibo ou ticket de cozinha é impresso:

1. Pagamento confirmado: O caixa marca um pedido como pago, ou um ticket de cozinha é acionado manualmente.
2. Backend formata o recibo: O servidor RestaurantManage executa o ReceiptFormattingService, que constrói o layout do recibo usando ReceiptBuilder e o converte em comandos de bytes ESC/POS via EscPosCommands e EscPosRasterEncoder.
3. Dados enviados via PrintHub: Os bytes do recibo formatado (codificados como Base64) são transmitidos por um canal WebSocket seguro (SignalR PrintHub) para o Print Agent correto — identificado pelo ID do seu restaurante.
4. Print Agent recebe o trabalho: O serviço Windows executando no PC local recebe o payload Base64, decodifica-o de volta para bytes ESC/POS brutos e identifica qual impressora usar.
5. Saída da impressora: Os bytes decodificados são enviados diretamente para a impressora térmica via TCP de rede, Windows Spooler ou USB — e o recibo é impresso em segundos.

O que está incluído em um recibo impresso

Cada recibo gerado pelo RestaurantManage inclui um conjunto completo de detalhes da transação. O cabeçalho mostra o nome, endereço e logotipo do restaurante (se configurado). O corpo inclui o número da mesa, uma lista numerada de todos os itens pedidos com quantidades e preços unitários, descontos aplicáveis e um detalhamento fiscal por categoria tributária. O rodapé mostra o total do pedido, método de pagamento (dinheiro, cartão, etc.), data e hora do pagamento e uma mensagem de agradecimento opcional. Os tickets de cozinha seguem um formato simplificado mostrando apenas o número da mesa, nomes dos itens, quantidades e quaisquer notas.

Quando os recibos são acionados

Recibos de clientes são impressos automaticamente quando o caixa confirma o pagamento total ou parcial de um pedido. Tickets de cozinha são impressos quando um novo pedido é enviado do painel do caixa ou do aplicativo móvel do garçom. Em ambos os casos, o trabalho de impressão é totalmente gerenciado pelo backend e roteado para o Print Agent automaticamente. Funcionários autorizados também podem iniciar uma reimpressão no painel de administração se a impressão original foi perdida ou estava ilegível.

Como instalo o Print Agent?

A instalação leva cerca de cinco minutos em qualquer PC moderno com Windows. O PC deve permanecer ligado durante o horário de serviço do restaurante, pois o Print Agent executa como um serviço Windows em segundo plano.

1. Baixar: Obtenha o instalador mais recente do Print Agent no seu painel de administração ou entre em contato com o suporte.
2. Instalar: Execute o instalador em um PC Windows que permanecerá ligado durante o horário de serviço.
3. Configurar: Abra o config.json e insira a URL base da API, o ID do restaurante e a chave secreta do agente (fornecida pelo seu administrador).
4. Conectar a impressora: Conecte sua impressora térmica via USB ou ligue-a à mesma rede que o PC.
5. Iniciar o serviço: Execute o Print Agent — ele se conecta ao PrintHub automaticamente e exibe um indicador de status verde.
6. Impressão de teste: Processe um pagamento de teste no painel do caixa e verifique se o recibo é impresso corretamente.

Requisitos do sistema

O Print Agent tem requisitos mínimos de hardware, mas depende de um sistema operacional e ambiente de execução compatíveis:

• Sistema operacional: Windows 10 (versão 1909 ou posterior) ou Windows 11. O Print Agent é um serviço exclusivo do Windows e não funciona em macOS ou Linux.
• Ambiente de execução: .NET 8 Runtime deve estar instalado. O instalador solicitará que você o baixe se não estiver presente — é gratuito da Microsoft.
• Conexão com a internet: Uma conexão estável com a internet é necessária para se comunicar com a nuvem do RestaurantManage. O agente se reconecta automaticamente após interrupções breves.
• Acesso à rede: O PC deve conseguir acessar a impressora — seja por cabo USB ou no mesmo segmento de rede local.
• Processador e RAM: Qualquer processador moderno com pelo menos 512 MB de RAM disponível é suficiente. O agente é muito leve.

Executar como serviço do Windows

Para uso em produção, o Print Agent deve ser instalado como serviço do Windows para que inicie automaticamente quando o PC for ligado — mesmo antes de um usuário fazer login. Para registrá-lo como serviço, clique com o botão direito em install-service.bat e escolha Executar como administrador. Isso registra o agente no Gerenciador de controle de serviços do Windows com o nome RestaurantPrintAgent. Após a instalação, você pode gerenciá-lo no painel Serviços (services.msc) ou via linha de comando com sc start RestaurantPrintAgent e sc stop RestaurantPrintAgent. Para remover o serviço, execute uninstall-service.bat como administrador.

Encontrar seu ID de restaurante e chave secreta

O ID do restaurante é o identificador único do seu restaurante no sistema RestaurantManage. Você pode encontrá-lo no painel de administração em Configurações → Informações do restaurante. A Chave secreta do agente é uma credencial separada que autentica o Print Agent com o endpoint WebSocket do PrintHub — não é a mesma que a sua senha de usuário. Para gerar ou regenerar uma chave secreta, acesse Configurações → Print Agent no painel de administração e clique em Gerar nova chave. Copie a chave imediatamente e cole-a no config.json — ela não será exibida novamente após a navegação. Se perder a chave, simplesmente gere uma nova; a antiga será invalidada automaticamente.

Quais tipos de conexão de impressora são suportados?

O Print Agent suporta três métodos de conexão com alternância automática entre eles. Impressoras de rede, impressoras USB e conexões Windows Spooler são todas suportadas. O agente tenta primeiro o Spooler, depois passa para USB direto e finalmente tenta compartilhamentos de rede UNC.

Impressoras de rede (recomendado)

Impressoras de rede são o método de conexão recomendado para a maioria dos restaurantes. Uma impressora térmica conectada à rede tem seu próprio endereço IP e aceita dados de impressão brutos na porta TCP 9100 — a porta padrão para impressão ESC/POS. Para configurar, conecte a impressora ao roteador ou switch com um cabo Ethernet, depois use a página de configuração integrada da impressora ou o menu do painel frontal para atribuir um endereço IP estático (ex.: 192.168.1.100). Insira esse endereço IP e a porta 9100 na configuração do Print Agent. O IP estático é importante — se a impressora receber um novo IP do DHCP a cada reinicialização, os trabalhos de impressão falharão.

Impressoras USB e Windows Spooler

Impressoras térmicas USB se conectam diretamente ao PC Windows que executa o Print Agent. Após conectar o cabo USB, instale o driver Windows do fabricante se necessário (muitas impressoras ESC/POS modernas usam um driver genérico incluído no Windows). O Print Agent detectará a impressora via Windows Spooler. Se a impressora não aparecer no Spooler, o método de endereçamento USB direto pode ser tentado: o agente pode escrever diretamente em caminhos de dispositivos USB como \\?\USB001 ou caminhos de porta paralela como LPT1.

Ordem de alternância automática

Quando um trabalho de impressão é recebido, o Print Agent tenta os métodos de conexão nesta ordem: 1) Windows Spooler — se a impressora estiver registrada no Windows e acessível via Spooler, este método é usado primeiro. 2) USB direto — se o Spooler falhar, o agente tenta escrever diretamente em caminhos de dispositivos USB (USB001, USB002, etc.) e portas LPT. 3) Compartilhamento de rede UNC — como último recurso, o agente tenta acessar a impressora via caminho de compartilhamento de rede Windows. Se os três métodos falharem, o erro é registrado na pasta logs/ com detalhes.

Como configuro o Print Agent?

O Print Agent é configurado por meio de um único arquivo config.json localizado no diretório de instalação. Todas as configurações são em texto simples e entram em vigor na próxima vez que o serviço iniciar (ou reiniciar). Não há interface gráfica para configuração — editar o arquivo com qualquer editor de texto é suficiente.

Explicação do arquivo config.json

O arquivo de configuração tem três campos obrigatórios e aceita configurações opcionais de impressora:

• ApiBaseUrl: A URL base do seu servidor RestaurantManage, por exemplo <code>https://restaurantmanage.xyz</code>. Não inclua uma barra diagonal no final. O Print Agent usa esta URL para se conectar ao PrintHub e verificar atualizações.
• RestaurantId: O identificador único do seu restaurante. Você pode encontrá-lo no painel de administração em Configurações → Informações do restaurante.
• AgentSecretKey: A chave secreta gerada no painel de administração em Configurações → Print Agent. Esta chave autentica o agente com o servidor sem precisar de login de usuário. Mantenha-a confidencial.

Um exemplo completo de config.json tem esta aparência: {"ApiBaseUrl": "https://restaurantmanage.xyz", "RestaurantId": "seu-id-restaurante", "AgentSecretKey": "sua-chave-secreta"}. Após editar o arquivo, reinicie o serviço Print Agent para que as alterações entrem em vigor.

Configuração do nome e IP da impressora

Para impressoras de rede, você precisa do endereço IP da impressora. Para encontrá-lo: a maioria das impressoras térmicas imprime uma página de configuração ao manter o botão de alimentação pressionado durante a inicialização — o endereço IP está listado lá. Alternativamente, verifique a lista de clientes DHCP do seu roteador para encontrar o nome do host da impressora. Depois de obter o IP, atribua-o como endereço estático nas configurações de rede da impressora. Para impressoras Windows Spooler, o nome da impressora deve corresponder exatamente ao que aparece em Configurações do Windows → Impressoras e scanners. Os nomes de impressoras diferenciam maiúsculas de minúsculas.

Arquivos de log e diagnóstico

O Print Agent grava logs detalhados na subpasta logs/ dentro do diretório de instalação. Os arquivos de log são nomeados por data (ex.: log-2026-04-06.txt) e são rotacionados diariamente. Cada entrada de log inclui um carimbo de data/hora, nível de gravidade (INFO, AVISO, ERRO) e uma descrição do que ocorreu. Se você estiver solucionando uma falha de impressão, verifique o arquivo de log da data do problema — a mensagem de erro exata indicará se o problema está relacionado à rede, autenticação ou impressora.

Como funciona a atualização automática?

O Print Agent verifica atualizações aproximadamente a cada 2,5 horas chamando o endpoint de atualização no servidor RestaurantManage. Se uma nova versão estiver disponível, ele baixa o pacote de atualização como arquivo ZIP para uma pasta de atualizações pendentes, executa o script de instalação e reinicia o serviço automaticamente. Isso significa que seu restaurante sempre executa a versão mais recente sem intervenção manual. As verificações de atualização incluem um jitter de temporização por restaurante para evitar que todos os agentes se atualizem simultaneamente.

Solução de problemas comuns

A maioria dos problemas de impressão se enquadra em uma de três categorias: problemas de conexão, problemas de hardware da impressora ou erros de configuração. Os arquivos de log na pasta logs/ são o melhor ponto de partida para diagnosticar qualquer problema.

Erros de conexão e autenticação

• O agente não se conecta ao servidor: Verifique se ApiBaseUrl no config.json está correto e acessível pelo PC. Abra um navegador no mesmo PC e acesse a URL da API — você deve ver uma resposta. Verifique se o PC tem uma conexão ativa com a internet.
• Falha de autenticação (erro 401 nos logs): AgentSecretKey está incorreto ou foi regenerado. Faça login no painel de administração, gere uma nova chave em Configurações → Print Agent, atualize o config.json e reinicie o serviço.
• A conexão cai e reconecta repetidamente: Isso geralmente indica um problema de instabilidade de rede. Mude de Wi-Fi para Ethernet com fio. Verifique se um firewall ou antivírus está bloqueando conexões WebSocket de saída (o agente usa HTTPS porta 443).
• O agente se conecta mas não recebe trabalhos de impressão: Confirme que o ID do restaurante no config.json corresponde exatamente ao do painel de administração (diferencia maiúsculas de minúsculas). Verifique também se o Print Agent está ativado em Configurações → Print Agent.

Problemas de qualidade de impressão e codificação

• Caracteres ou símbolos ilegíveis no recibo: Sua impressora térmica pode não suportar completamente o conjunto de comandos ESC/POS usado pelo RestaurantManage. Consulte a documentação da impressora para verificar compatibilidade. A maioria das impressoras térmicas de 58 mm e 80 mm fabricadas após 2015 é compatível.
• O recibo é impresso mas o texto está cortado: A configuração de largura do papel pode estar incorreta. O RestaurantManage formata recibos para papel de 80 mm por padrão. Se você usar uma impressora de 58 mm, entre em contato com o suporte para habilitar o modo de papel estreito.
• O recibo é impresso em branco ou apenas com conteúdo parcial: Isso pode indicar um rolo de papel vazio ou uma cabeça de impressão entupida. Substitua o papel e limpe a cabeça de impressão com um pano seco. Se o problema persistir, teste a impressora diretamente pelo Windows para isolar se é problema de hardware ou software.
• Caracteres especiais ou texto árabe/RTL não são impressos corretamente: Certifique-se de que o conjunto de caracteres da sua impressora está configurado para UTF-8 ou a página de código adequada para seu idioma. Essa configuração geralmente é acessível no menu de configuração da impressora.

Falhas de inicialização do serviço

• O agente não inicia como serviço do Windows: Você deve executar install-service.bat como Administrador (clique com botão direito → Executar como administrador). Sem permissões elevadas, o serviço não pode ser registrado no Gerenciador de controle de serviços do Windows.
• O serviço inicia e então para imediatamente: Verifique o Visualizador de Eventos do Windows (eventvwr.msc) em Logs do Windows → Aplicativo para mensagens de erro do RestaurantPrintAgent. Verifique também a pasta logs/ para erros de inicialização. Causas comuns são config.json ausente ou malformado, runtime .NET 8 ausente ou conflito de portas.
• Runtime .NET ausente: Baixe e instale o .NET 8 Runtime de https://dotnet.microsoft.com. Após a instalação, reinicie o serviço Print Agent.
• Firewall bloqueando o agente: O Windows Defender ou um firewall de terceiros pode estar bloqueando a conexão de saída do agente. Adicione uma exceção para o executável do Print Agent nas configurações do firewall.

Guias relacionados

• Painel do caixa: Como processar pagamentos que acionam a impressão de recibos
• Tela de cozinha: Como a impressão de tickets de cozinha se integra ao fluxo de pedidos
• Primeiros passos: Guia completo de configuração do cadastro ao primeiro pedido