Brasil NFe Agente
Visão geral
O Brasil NFe Agente é um programa leve, instalado no computador da empresa (Windows ou Linux), que faz duas coisas para o Brasil NFe sem que o certificado digital saia da máquina:
- Assinatura remota com o certificado local. O servidor monta o documento fiscal, envia ao Agente só o trecho a assinar, o Agente assina com o certificado A1 (arquivo) ou A3 (token) da própria máquina e faz a conexão mTLS com a SEFAZ dali mesmo. A chave privada nunca é transmitida.
- NFC-e off-line no PDV. O Agente sobe uma API HTTP local no caixa (
http://127.0.0.1:9155) com o mesmo contrato da API do Brasil NFe (POST /services/Fiscal/EnviarNotaFiscal). Com o servidor no ar, a nota é encaminhada e autorizada online. Sem servidor, o Agente monta e assina a NFC-e em contingência off-line (tpEmis 9) no caixa, devolve XML + DANFE em cerca de um segundo, guarda a nota e a envia sozinho quando a conexão volta; o Brasil NFe transmite à SEFAZ.
Um único pareamento (o código gerado no painel) liga os dois recursos. Não existe "habilitar off-line": toda empresa pareada já emite NFC-e off-line.
Download: www.brasilnfe.com.br/agente (Windows
.exe, Linux AppImage/.deb/.rpme binário headless para servidores). Versão atual, tamanho e SHA-256 de cada instalador aparecem na própria página.
Para quem é
| Cenário | O que o Agente resolve |
|---|---|
A empresa não quer enviar o .pfx para a nuvem, por política interna ou exigência do cliente. | Assina localmente; o servidor nunca tem a chave. |
| A empresa usa token A3 (cartão ou USB), que não tem arquivo exportável. | Assina pelo módulo PKCS#11 do fabricante ou pela loja de certificados do Windows. |
| Loja com PDV que precisa continuar vendendo quando a internet cai. | NFC-e em contingência off-line no caixa, com transmissão automática depois. |
| Rede de lojas com vários CNPJs e vários caixas por loja. | Um Agente por loja atende N caixas pela rede local; N empresas no mesmo Agente. |
| Servidor Linux sem tela (VPS, container, servidor de loja). | Mesmo binário em modo headless, como serviço systemd, com toda a CLI. |
Se a sua empresa envia o certificado A1 ao servidor e não tem PDV, você não precisa do Agente: a API funciona sem nenhum programa instalado (ver Certificado Digital).
Arquitetura em uma tela
Code
- Servidor Brasil NFe: continua dono da regra fiscal. Monta os XMLs, valida, fala com a SEFAZ, guarda as notas, gera DANFE e eventos. Nada muda para quem integra pela API.
- Agente: assina com o certificado local, faz a conexão com a SEFAZ quando pedido, expõe a API local para o PDV, guarda a fila off-line e sincroniza.
- Pacote fiscal off-line: componente publicado pelo Brasil NFe com as mesmas regras fiscais do servidor. É baixado pelo Agente na primeira conexão, verificado por assinatura digital e usado só quando o servidor está inalcançável. Não tem acesso ao certificado: cada assinatura é feita pelo Agente.
O que muda para quem integra
| Integração | Mudança |
|---|---|
| API REST (NF-e, NFS-e, CT-e, MDF-e, eventos, consultas) | Nenhuma. O Agente é transparente: a assinatura passa a acontecer na máquina do cliente, mas endpoints, JSON e respostas são os mesmos. |
| Sistema de vendas (PDV) que emite NFC-e | Troca a base URL de https://api.brasilnfe.com.br para http://127.0.0.1:9155 (ou o IP do servidor da loja) e para de enviar o token de API. Série, número e cNF passam a ser preenchidos pelo Agente. Detalhes em NFC-e off-line. |
| PDV que roda no navegador (PWA) | Além do item acima, a origem do site do PDV precisa ser autorizada no Agente (nfce config --origem https://pdv.suaempresa.com.br). |
Começando em três passos
- Instale a versão da sua plataforma: Instalação.
- Pareie com o código gerado no painel em Configurações › aba Agente e escolha o certificado: Pareamento e certificado.
- Se houver PDV, aponte-o para a API local e, se ele roda no navegador, autorize a origem: NFC-e off-line.
Tudo o que se faz na interface gráfica também se faz por linha de comando e, de longe, pelo console da aba Agente do painel: CLI e console remoto.
Plataformas e modos de execução
| Distribuição | Alvo | Modo | Atualização |
|---|---|---|---|
Windows 10/11 64 bits, instalador .exe | windows-x64 | Interface gráfica (bandeja) e CLI no mesmo executável | Automática (instalador silencioso) |
| Linux AppImage x86_64 | linux-x64 | Interface gráfica; sem DISPLAY entra em modo headless sozinho | Automática (troca o binário) |
Linux .deb (Ubuntu 22.04+/Debian 12+) | linux-x64-deb | Interface gráfica ou headless | Pelo gerenciador de pacotes (o Agente só avisa) |
Linux .rpm (Fedora/RHEL/openSUSE) | linux-x64-rpm | Interface gráfica ou headless | Pelo gerenciador de pacotes (o Agente só avisa) |
| Linux binário headless (qualquer x86_64 de 2020+) | linux-x64-headless | Só CLI/serviço, sem dependências gráficas | Automática |
| macOS | - | Em desenvolvimento | - |
A versão instalada, o alvo de atualização e a plataforma aparecem em nfce status e na aba Agente do painel.
Segurança em resumo
- Certificado e chave privada nunca saem do Agente, nem para o pacote fiscal off-line.
- O token da API nunca trafega: nem no navegador, nem no Agente. A credencial do Agente é o código de pareamento, revogável no painel.
- A API local escuta em
127.0.0.1por padrão e só aceita navegadores de origens autorizadas (403 fora da lista). - Pacote off-line e atualizações só rodam com assinatura digital válida e hash conferido.
- A conexão mTLS aceita apenas domínios oficiais das SEFAZ; o console remoto executa uma lista fechada de comandos.
Detalhes e recomendações operacionais em Segurança.
Ver também
- Certificado Digital (A1 ICP-Brasil) - as duas formas de assinar: A1 no servidor ou Agente.
- Contingência - como o servidor trata SEFAZ fora do ar (diferente de servidor fora do ar).
- Referência da API -
EnviarNotaFiscal, o contrato que a API local do Agente replica.
Last modified on