Novo · NFC-e off-line no caixa
Ícone do Brasil NFe Agente Brasil NFe Agente · Windows e Linux

Seu certificado fica com você. Seu caixa não para sem internet.

Um programa leve, instalado na máquina da empresa, que assina os documentos fiscais com o certificado local (A1 ou A3) e mantém a emissão de NFC-e funcionando em contingência quando a conexão cai. Quando a internet volta, ele transmite tudo sozinho.

Baixar para Windows Todas as plataformas Documentação

Versão 0.1.0 · atualiza sozinho · sem custo adicional para clientes do plano NF-e/NFC-e · requisitos

brasilnfe-agent nfce status 
$ brasilnfe-agent nfce status
API local        http://127.0.0.1:9155   no ar
Servidor         api.brasilnfe.com.br    inalcançável
Modo             automático              emitindo off-line
Pacote fiscal    afa11b457bd178e4        verificado
Empresa          12.345.678/0001-95      série 500 · próximo nº 128
Notas            3 pendentes · 0 no servidor · 1.240 transmitidas

-- 14:32  conexão restabelecida
-- 14:32  3 notas enviadas ao servidor
-- 14:41  3 notas autorizadas pela SEFAZ
Notas            0 pendentes · 0 no servidor · 1.243 transmitidas
Download

Escolha a sua plataforma

O mesmo programa em todas: interface gráfica para o balcão, linha de comando para quem automatiza e binário puro para servidores sem tela.

Versão 0.1.0 Instaladores publicados pelo Brasil NFe e verificados por hash SHA-256.

Linux · AppImage

Portátil · x86_64

Um arquivo só, roda em qualquer distribuição moderna sem instalar. Abre a interface gráfica; sem tela, entra automaticamente em modo terminal.

  • Ubuntu 22.04+, Debian 12+ ou equivalente
  • chmod +x e execute; atualiza sozinho
  • Certificado .pfx ou token A3 (PKCS#11)
Baixar AppImage
Verificar SHA-256disponível após a publicação da versão
--

Linux · Servidor (headless)

Binário único · sem interface

Para o servidor da loja, VPS ou container. Sem dependências gráficas, roda como serviço do sistema e atende todos os caixas pela rede.

  • Qualquer Linux x86_64 de 2020 em diante (Ubuntu 20.04+)
  • Mesmos comandos da versão com interface
  • Exemplo de serviço systemd na documentação
Baixar binário
Verificar SHA-256disponível após a publicação da versão
--

Ubuntu / Debian

Pacote .deb · amd64

Instalação pelo gerenciador de pacotes, com as dependências resolvidas automaticamente. Ideal para quem já gerencia máquinas com apt.

  • Ubuntu 22.04+ ou Debian 12+
  • sudo apt install ./brasil-nfe-agente_*.deb
  • Atualização pelo próprio pacote
Baixar .deb
Verificar SHA-256disponível após a publicação da versão
--

Fedora / RHEL / openSUSE

Pacote .rpm · x86_64

Para distribuições baseadas em RPM. Mesma interface, mesmos comandos e mesma API local das outras versões.

  • Fedora, RHEL/Rocky/Alma 9+, openSUSE
  • sudo dnf install ./brasil-nfe-agente-*.rpm
  • Atualização pelo próprio pacote
Baixar .rpm
Verificar SHA-256disponível após a publicação da versão
--
Em breve

macOS

Em desenvolvimento

A versão para Mac está em desenvolvimento. Enquanto isso, o certificado A1 pode ser enviado ao servidor pelo painel, sem nenhum programa instalado.

  • Mesmo código do Windows e Linux
  • Assinatura e notarização Apple previstas
Avise-me quando lançar

Precisa de outra plataforma ou de um pacote assinado para distribuição interna? Fale com a equipe. Instruções de instalação, pareamento e serviço systemd na documentação de instalação.

Um pareamento, dois superpoderes

O que o Agente faz pela sua empresa

Você cola um código gerado no painel, escolhe o certificado e pronto: os dois recursos ficam ativos ao mesmo tempo, sem configuração extra.

Certificado local

Assine sem enviar o certificado para a nuvem

O Brasil NFe monta a nota, o Agente assina na sua máquina e conversa com a SEFAZ dali mesmo. A chave privada nunca é transmitida, nem para nós.

  • Certificado A1 em arquivo (.pfx/.p12), A3 em token ou cartão USB e certificados já instalados no Windows
  • Senha e PIN guardados no cofre do sistema operacional, não em texto
  • Várias empresas (um certificado por CNPJ) no mesmo Agente
  • Trilha de auditoria local de tudo o que foi assinado
  • Revogação imediata pelo painel: o Agente é desconectado na hora
NFC-e off-line

O PDV continua vendendo quando a internet cai

O sistema de vendas aponta para a API local do Agente e envia o mesmo JSON de sempre. Com servidor no ar, a nota é autorizada online; sem servidor, ela é emitida em contingência no próprio caixa, com DANFE e QR Code, em cerca de um segundo.

  • Mesmo contrato da API: troque só o endereço, sem reescrever a integração
  • Numeração própria do caixa: online e off-line nunca colidem
  • Fila sincronizada a cada 30 s; o Brasil NFe transmite à SEFAZ e devolve o protocolo
  • Reimpressão do DANFE, XML, reenvio e correção direto no Agente ou pelo painel
  • Três camadas de backup: nenhuma nota se perde, nenhum número se repete
Como funciona

Do download ao caixa emitindo em três passos

Menos de cinco minutos, sem mexer no banco de dados e sem cadastrar série no painel.

1

Instale

Baixe a versão da sua plataforma e instale. No Windows e no Linux com tela abre uma interface guiada; em servidor, use o binário e os mesmos comandos no terminal.

2

Pareie com o código do painel

No painel do Brasil NFe, em Configurações › Agente, gere o código de pareamento. Cole no Agente e escolha o certificado. Isso já liga a assinatura local e a NFC-e off-line.

3

Aponte o PDV para o Agente

Troque a base da API por http://127.0.0.1:9155 no seu sistema de vendas. Sem token, mesmo JSON. Se o PDV roda no navegador, autorize a origem dele na configuração.

PDV → Agente · mesmo JSON da API, sem token 
POST http://127.0.0.1:9155/services/Fiscal/EnviarNotaFiscal
Content-Type: application/json
X-Empresa-CNPJ: 12345678000195   // só se houver mais de uma empresa pareada

{ "ModeloDocumento": 65, "Cliente": { ... }, "Produtos": [ ... ], "Pagamentos": [ ... ] }

// resposta com o servidor fora do ar: NFC-e emitida em contingência no caixa
{
  "ReturnNF": { "Ok": true, "Serie": 500, "Numero": 128, "ChaveNF": "3526091234...9123456780",
                "CodStatusRespostaSefaz": 100, "DsStatusRespostaSefaz": "NFC-e emitida em contingência off-line; será transmitida quando a conexão voltar" },
  "Base64Xml":  "PE5GZSB4bWxucz0...",   // XML assinado (tpEmis 9)
  "Base64File": "PCFET0NUWVBFIGh0bWw...",   // DANFE NFC-e pronto para imprimir
  "Avisos": ["Emitida off-line (contingência) pelo BrasilNFe Agent; aguardando transmissão à SEFAZ."]
}
Contingência off-line, de verdade

O que acontece quando a internet cai no meio da venda

O cliente não espera, o operador não faz nada diferente e a SEFAZ recebe a nota assim que a conexão volta.

1. Venda fechada

O PDV envia a NFC-e para a API local, como sempre.

2. Tenta online

O Agente encaminha ao Brasil NFe. Respondeu? Nota autorizada normalmente.

servidor no ar

3. Sem resposta

Em segundos o Agente assume: monta e assina a NFC-e em contingência (tpEmis 9) no caixa.

off-line

4. DANFE na hora

XML assinado e DANFE com QR Code off-line voltam em cerca de 1 s. O cliente vai embora com o cupom.

5. Conexão volta

A cada 30 s o Agente testa o servidor e sobe a fila. Nada a fazer no caixa.

6. SEFAZ autoriza

O Brasil NFe transmite, recebe o protocolo e o Agente marca a nota como transmitida.

protocolo
~1 spara emitir off-line
30 sintervalo de sincronização
0 notasperdidas: 3 camadas de backup
24 hprazo legal; alerta a partir de 12 h
Mesmo JSONda API que você já usa
Um Agente, quantos caixas precisar

Instale num servidor da loja e aponte todos os PDVs

Uma empresa fica pareada com um Agente por vez. Por isso o desenho recomendado para lojas com vários caixas é simples: um computador da loja (pode ser o próprio servidor, com ou sem tela) roda o Agente escutando na rede local, e cada PDV aponta para ele. Redes com várias filiais? Um Agente por loja, com o código de pareamento de cada CNPJ.

  • Servidor de loja

    Configure a API local para escutar em 0.0.0.0 e os caixas chamam http://ip-do-servidor:9155. Funciona no Windows ou no Linux headless como serviço.

  • Várias empresas no mesmo Agente

    Cada CNPJ tem seu código, sua série e seu contador. O PDV informa a empresa pelo header X-Empresa-CNPJ.

  • PDV no navegador (PWA) ou desktop

    Sistemas web autorizam a origem no Agente; sistemas desktop chamam direto. Nenhum dos dois precisa conhecer o token da API.

  • Um caixa só

    Instale no próprio computador do caixa e use o endereço padrão 127.0.0.1:9155. Nada mais a configurar.

Brasil NFeapi.brasilnfe.com.br · SEFAZ
WebSocket seguro + fila de notas off-line
Brasil NFe Agenteservidor da loja · certificado · API local :9155
rede local da loja
Caixa 1
Caixa 2
PDV web
Retaguarda
Do jeito que a sua equipe trabalha

Interface gráfica, terminal ou painel: você escolhe

É um único executável. Tudo o que dá para fazer na tela dá para fazer por comando, e tudo o que dá para fazer por comando dá para fazer de longe, pelo painel do Brasil NFe.

Aplicativo com interface

Onboarding guiado, lista de empresas com status em tempo real (conectado, assinando, reconectando), tela de NFC-e com situação, notas e configuração, e ajustes de inicialização automática, notificações e atualização. Fecha para a bandeja e segue trabalhando.

Linha de comando

O mesmo executável aceita subcomandos: pair, run, nfce status, nfce notas, nfce nota CHAVE danfe, nfce config --origem ..., update apply. Perfeito para provisionar lojas por script e rodar como serviço systemd.

Console remoto no painel

Na aba Agente do painel você vê versão, máquina, fila off-line e série de cada loja, e executa os mesmos comandos de longe: reimprimir um DANFE, reenviar uma nota, ajustar a numeração ou atualizar o Agente sem ir até o caixa.

RecursoInterface gráficaLinha de comando / headlessConsole remoto (painel)
Parear empresa e escolher certificadoSimSim (pair)Gera e revoga o código
Situação da API local, servidor e filaSim, atualizada a cada 5 snfce statusSim, telemetria a cada ~2 min
Listar notas, DANFE, XML, reenviarSimnfce notas, nfce notaSim, DANFE abre em nova aba
Corrigir nota ainda no caixa (JSON ou XML)Simnfce nota CHAVE corrigirSim
Série, ambiente, próximo número, origens, portaSimnfce config ...Sim
Modo de teste (contingência forçada)Sim--modo contingenciaSim
Verificar e aplicar atualizaçãoSimupdate check / applySim
Iniciar com o sistemaOpção nas configuraçõesServiço systemd-
Certificados

Funciona com o certificado que você já tem

A1 ou A3, em arquivo, token, cartão ou já instalado no Windows. O Agente confere se o certificado pertence ao CNPJ do código de pareamento antes de salvar.

A1 em arquivo (.pfx / .p12)

Selecione o arquivo e informe a senha. Compatível com os certificados ICP-Brasil legados (cifra RC2-40) que outros programas rejeitam. A senha vai para o cofre do sistema.

A3 em token ou cartão

Aponte o módulo PKCS#11 do fabricante (SafeNet, Watchdata, Gemalto e outros), escolha o slot se houver mais de um e informe o PIN. A chave nunca sai do dispositivo.

Certificado instalado no Windows

Lista os certificados do repositório pessoal do Windows com chave privada, sejam A1 importados ou A3 com driver do fabricante. Sem arquivo, sem caminho de módulo.

Assinatura XML-DSig RSA-SHA1 exigida pela SEFAZ
Conexão mTLS com a SEFAZ feita pela sua máquina
Raízes ICP-Brasil embutidas (v5 e v10)
Proxy HTTP corporativo suportado
Aviso de vencimento do certificado na tela
Diagnóstico de conexão com a SEFAZ por comando
Segurança

Feito para rodar na máquina do cliente sem abrir brechas

Cada ponto onde algo poderia vazar foi fechado por desenho, não por configuração.

A chave privada nunca sai

Nem para o Brasil NFe, nem para o pacote fiscal local. Quem precisa de uma assinatura pede ao Agente e recebe só o resultado.

O token da API nunca trafega

O PDV não envia token. O Agente se identifica com o código de pareamento, que pode ser revogado no painel a qualquer momento.

Pacotes assinados digitalmente

O pacote fiscal off-line e cada atualização do Agente só rodam com assinatura digital válida e hash conferido arquivo por arquivo.

Só fala com a SEFAZ

A conexão mTLS aceita apenas os domínios oficiais das SEFAZ; o Agente não pode ser usado como proxy com o seu certificado.

API local com lista de origens

Por padrão escuta só em 127.0.0.1 e nenhuma página web consegue chamar sem estar na lista de origens autorizadas.

Console remoto com lista fechada

O painel só executa comandos conhecidos do próprio Agente. Nunca shell, nunca código arbitrário.

Segredos no cofre do sistema

Senha do certificado e PIN ficam no Gerenciador de Credenciais, Keychain ou Secret Service; em servidor, em arquivo com permissão restrita.

Auditoria local

Cada assinatura gera um registro com data, empresa, certificado e hash do que foi assinado, para investigar qualquer uso indevido.

FAQ

Perguntas frequentes sobre o Brasil NFe Agente

Dúvidas comuns de quem vai instalar no caixa, no servidor da loja ou no escritório.

Não. A API funciona sem nenhum programa instalado quando o certificado A1 é enviado ao servidor pelo painel. O Agente é para quem quer manter o certificado (A1 ou A3) na própria máquina, ou quer que o PDV continue emitindo NFC-e mesmo sem internet. Se a empresa já tem certificado no servidor e mesmo assim pareia o Agente, ele é usado só para a NFC-e off-line.
Nunca. O servidor monta o documento e envia apenas o trecho a assinar; o Agente assina localmente e devolve só a assinatura e o certificado público. A conexão com a SEFAZ (mTLS) também é feita pela sua máquina. A chave privada não é transmitida em nenhum momento, e o pacote fiscal que emite NFC-e off-line também pede a assinatura ao Agente em vez de ter acesso à chave.
O sistema de vendas envia a nota para a API local do Agente (http://127.0.0.1:9155), com o mesmo JSON da API do Brasil NFe. Se o servidor responde, a nota é autorizada online, como sempre. Se não responde, o Agente monta e assina a NFC-e em contingência off-line (tpEmis 9) no próprio caixa, devolve o XML e o DANFE em cerca de um segundo e guarda a nota. Quando a conexão volta, envia a fila automaticamente e o Brasil NFe transmite à SEFAZ. Detalhes na documentação da NFC-e off-line.
O gatilho é o servidor do Brasil NFe não responder, seja porque a loja perdeu a internet, seja por qualquer outro motivo. Se a internet está ok mas a SEFAZ está fora, quem trata a contingência é o próprio servidor, como já acontece hoje. Nos dois casos o caixa não para.
Sim. Basta autorizar a origem do seu sistema (por exemplo https://pdv.suaempresa.com.br) na configuração do Agente, pela tela, pelo comando nfce config --origem ou pelo painel. A página passa a chamar a API local sem precisar de token de API: o Agente se identifica no servidor pelo código de pareamento. Sistemas desktop chamam direto, sem essa etapa.
Instale um único Agente em um computador da loja (pode ser um servidor local, com ou sem tela) e configure a API local para escutar na rede (0.0.0.0). Todos os PDVs apontam para http://ip-do-servidor:9155. Uma empresa fica pareada com um Agente por vez, e esse Agente atende quantos caixas forem necessários, cada nota com número sequencial da série do caixa.
Sim. O Agente suporta certificado A1 em arquivo (.pfx/.p12), A3 em token ou cartão USB (via módulo PKCS#11 do fabricante) e certificados já instalados na loja do Windows. Token A3 exige a máquina física com o dispositivo conectado, portanto não funciona em servidores na nuvem (VPS).
Sim. Ele consulta o Brasil NFe ao iniciar e a cada 6 horas; se houver versão nova, baixa, confere o hash SHA-256 e a assinatura digital do pacote e aplica sem intervenção (no Windows, instalador silencioso e reabertura; no Linux, troca do binário e reinício). Pode ser desligado nas configurações ou com BRASILNFE_AUTO_UPDATE=0. Instalações por .deb/.rpm avisam e atualizam pelo gerenciador de pacotes.
Cada NFC-e emitida off-line é gravada no banco local e também em um arquivo próprio, na mesma hora. O banco recebe cópias de segurança rotativas (no Windows, na pasta Documentos, que costuma sincronizar com o OneDrive). Ao iniciar, o Agente verifica a integridade do banco, restaura a cópia mais recente se preciso e reimporta as notas dos arquivos. A numeração nunca volta para trás, então nenhuma nota é perdida nem repetida.
Pode acontecer enquanto a assinatura de código Authenticode do instalador está em andamento. Confira o SHA-256 do arquivo com o valor exibido nesta página (botão "Verificar SHA-256") e prossiga em "Mais informações › Executar assim mesmo". As atualizações automáticas já são verificadas por assinatura digital pelo próprio Agente.
Ainda não. Hoje o Agente é distribuído para Windows (10 e 11, 64 bits) e Linux (AppImage, .deb, .rpm e binário para servidores). A versão para macOS está em desenvolvimento; enquanto isso, o certificado A1 pode ser enviado ao servidor pelo painel.
Comece agora

Instale hoje e nunca mais pare uma venda por falta de internet

Baixe, pareie com o código do painel e aponte o seu PDV. Se ainda não é cliente, crie sua conta e teste em homologação.

Baixar o Agente Falar com a equipe