# 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**:

1. **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.
2. **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](https://www.brasilnfe.com.br/agente/) (Windows `.exe`, Linux AppImage/`.deb`/`.rpm` e 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](/conceitos-fiscais/certificado-digital)).

## Arquitetura em uma tela

```
painel do Brasil NFe ──── gera o código de pareamento ────► Agente (pair)
                                                              │
   servidor Brasil NFe ◄──── WebSocket seguro (wss) ──────────┤  assinatura remota, status,
   (monta XML, fala com a SEFAZ                                │  comandos do console remoto
    ou pede ao Agente pra falar)                               │
          ▲                                                    ├──► API local http://127.0.0.1:9155
          │  fila de notas off-line (a cada 30 s)              │     (PDV manda o mesmo JSON, sem token)
          └────────────────────────────────────────────────────┘
                                                               └──► pacote fiscal off-line,
                                                                    baixado e verificado pelo Agente
```

- **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](/agente-docs/nfce-offline). |
| 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

1. **Instale** a versão da sua plataforma: [Instalação](/agente-docs/instalacao).
2. **Pareie** com o código gerado no painel em **Configurações › aba Agente** e escolha o certificado: [Pareamento e certificado](/agente-docs/pareamento-e-certificado).
3. Se houver PDV, **aponte-o para a API local** e, se ele roda no navegador, autorize a origem: [NFC-e off-line](/agente-docs/nfce-offline).

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](/agente-docs/cli-e-console).

## 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.1` por 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](/agente-docs/seguranca).

## Ver também

- [Certificado Digital (A1 ICP-Brasil)](/conceitos-fiscais/certificado-digital) - as duas formas de assinar: A1 no servidor ou Agente.
- [Contingência](/conceitos-fiscais/contingencia) - como o servidor trata SEFAZ fora do ar (diferente de servidor fora do ar).
- [Referência da API](/api) - `EnviarNotaFiscal`, o contrato que a API local do Agente replica.