# Instalação import { Tabs, TabsList, TabsTrigger, TabsContent } from "zudoku/ui/Tabs.js"; Downloads em [www.brasilnfe.com.br/agente](https://www.brasilnfe.com.br/agente/). Os links diretos, a versão atual, o tamanho e o SHA-256 de cada instalador também estão disponíveis em JSON público: `GET https://api.brasilnfe.com.br/services/Agent/Releases`. Cada arquivo é servido por `https://api.brasilnfe.com.br/services/Agent/Download?alvo=ALVO`. ## Requisitos | Item | Requisito | | --- | --- | | Windows | Windows 10 ou 11, 64 bits. | | Linux com interface (AppImage, `.deb`, `.rpm`) | Ubuntu 22.04+, Debian 12+ ou equivalente (o `.deb`/`.rpm` instala as dependências gráficas necessárias). | | Linux headless (binário) | Qualquer distribuição x86_64 de 2020 em diante (ex.: Ubuntu 20.04). Sem dependências gráficas. | | Certificado | A1 em arquivo `.pfx`/`.p12`, A3 em token/cartão (módulo PKCS#11 do fabricante instalado) ou certificado já instalado na loja do Windows. Token A3 exige a máquina física com o dispositivo: **não funciona em VPS**. | | Rede de saída | HTTPS/WSS (443) para `api.brasilnfe.com.br` e HTTPS para os servidores das SEFAZ. Proxy HTTP corporativo com túnel CONNECT é suportado (ver abaixo). | | Rede interna (opcional) | Se o Agente atender caixas pela rede local, liberar a porta da API local (padrão `9155`/TCP) no firewall da máquina. | | Disco | Menos de 100 MB para o Agente; o pacote fiscal off-line ocupa cerca de 45 MB compactados por versão (duas versões ficam no disco). Notas off-line ocupam poucos KB cada (JSON e XML em gzip). | ## Windows 1. Baixe o instalador (`windows-x64`, arquivo `Brasil NFe Agente__x64-setup.exe`) e execute. O instalador é em português e leva segundos. 2. O programa fica em `%LOCALAPPDATA%\Brasil NFe Agente\` e abre com a tela de boas-vindas. Fechar ou minimizar a janela **não encerra**: o Agente vai para a bandeja do sistema e continua assinando. Use o ícone da bandeja para reabrir ou sair. 3. Em **Configurações** (ícone de engrenagem) ative **Iniciar com o sistema** para o Agente subir no login, sem ninguém abrir. > **Aviso "Editor desconhecido" do Windows SmartScreen.** Pode aparecer enquanto a assinatura de código Authenticode do instalador está em andamento. Confira o SHA-256 do arquivo baixado com o valor exibido na página de download (`Get-FileHash .\Brasil*.exe` no PowerShell) e prossiga em "Mais informações › Executar assim mesmo". As atualizações automáticas são verificadas por assinatura digital pelo próprio Agente. **Linha de comando no Windows.** O mesmo `brasilnfe-agent.exe` do instalador tem a CLI inteira; com `> arquivo` ou `|` a saída vai direto para o destino. Detalhe do `cmd.exe`: o prompt volta antes da saída terminar; use `start /wait` quando precisar esperar. O instalador não adiciona a pasta ao `PATH`. ```powershell & "$env:LOCALAPPDATA\Brasil NFe Agente\brasilnfe-agent.exe" nfce status # cmd.exe, esperando o fim: start /wait "" "%LOCALAPPDATA%\Brasil NFe Agente\brasilnfe-agent.exe" nfce status ``` ## Linux com interface gráfica AppImage .deb (Ubuntu/Debian) .rpm (Fedora/RHEL) ```sh chmod +x "Brasil NFe Agente_0.1.0_amd64.AppImage" ./"Brasil NFe Agente_0.1.0_amd64.AppImage" # abre a interface ./"Brasil NFe Agente_0.1.0_amd64.AppImage" nfce status # CLI, mesmo arquivo ``` Sem servidor gráfico o AppImage entra automaticamente em modo headless, equivalente a `run`. A atualização automática troca o próprio arquivo e reinicia. ```sh sudo apt install ./brasil-nfe-agente_0.1.0_amd64.deb brasil-nfe-agente # interface brasil-nfe-agente nfce status # CLI ``` O pacote instala o binário como `brasil-nfe-agente` e resolve as dependências (`libwebkit2gtk-4.1`, GTK). Atualização: baixe o `.deb` novo e instale por cima (o Agente avisa quando há versão nova, mas não se atualiza sozinho nesse formato). ```sh sudo dnf install ./brasil-nfe-agente-0.1.0-1.x86_64.rpm # ou: sudo rpm -U arquivo.rpm brasil-nfe-agente brasil-nfe-agente nfce status ``` Mesmo comportamento do `.deb`: interface quando há tela, headless quando não há, atualização pelo gerenciador de pacotes. ## Linux headless (servidor, VPS, container) O binário `linux-x64-headless` é o **mesmo Agente** sem a interface, feito para rodar em praticamente qualquer Linux x86_64 (Ubuntu 20.04 em diante). É um arquivo único: copie, dê permissão de execução e use os mesmos subcomandos. ```sh chmod +x brasilnfe-agent sudo mv brasilnfe-agent /usr/local/bin/brasilnfe-agent # parear uma empresa (pede a senha do PFX no prompt, sem eco) brasilnfe-agent pair bna_... --pfx /caminho/certificado.pfx # conferir e rodar (ctrl-c encerra) brasilnfe-agent list brasilnfe-agent run ``` Na VPS não há cofre de senhas do sistema, então a senha do PFX fica em um arquivo da pasta de dados com permissão restrita ao usuário (`0600`). Rode o `pair` com o **mesmo usuário** que vai rodar o serviço: os dados ficam no `home` desse usuário. ### Serviço systemd (inicia no boot e reinicia sozinho) `/etc/systemd/system/brasilnfe-agent.service` (troque `usuario`): ```ini [Unit] Description=Brasil NFe Agente (headless) After=network-online.target Wants=network-online.target [Service] User=usuario ExecStart=/usr/local/bin/brasilnfe-agent run Restart=always RestartSec=5 Environment=RUST_LOG=brasilnfe_agent_lib=info # Proxy corporativo, se houver: # Environment=HTTPS_PROXY=http://usuario:senha@proxy.empresa.local:3128 # Environment=NO_PROXY=localhost,127.0.0.1,.interno.local [Install] WantedBy=multi-user.target ``` ```sh sudo systemctl daemon-reload sudo systemctl enable --now brasilnfe-agent journalctl -u brasilnfe-agent -f # logs ``` Com o `.deb`/`.rpm` instalado num servidor sem tela, o `ExecStart` é `/usr/bin/brasil-nfe-agente run`. A atualização automática do binário headless substitui o arquivo e reinicia; sob systemd isso é transparente. ## Pareamento (resumo) 1. No painel do Brasil NFe, **Configurações › aba Agente › Gerar código de pareamento**. O código começa com `bna_` e deve ser tratado como senha. 2. No Agente: - **Interface**: "Adicionar empresa", cole o código, escolha **Certificado instalado** (Windows), **A1 (arquivo .pfx)** ou **A3 (token PKCS#11)**, informe senha/PIN, **Validar certificado** e **Salvar e conectar**. - **CLI**: `brasilnfe-agent pair CODIGO --pfx ARQUIVO` (A1), `--module LIB [--slot N]` (A3) ou `--thumbprint SHA1` (loja do Windows), depois `run`. 3. O Agente confere se o certificado pertence ao CNPJ do código e recusa certificado de outra empresa. Uma empresa = um certificado; um Agente = N empresas (N códigos). Tudo sobre isso em [Pareamento e certificado](/agente-docs/pareamento-e-certificado). ## Servidor de loja atendendo vários caixas Uma empresa fica conectada a **um Agente por vez** (o servidor derruba a conexão anterior quando outra instância pareia com o mesmo código). Para uma loja com vários PDVs do mesmo CNPJ, o desenho é: 1. Instale o Agente em um computador da loja que fique ligado (servidor local, com ou sem tela). 2. Faça a API local escutar na rede: pela tela (NFC-e › Configuração › "Escutar em: toda a rede local") ou por comando: ```sh brasilnfe-agent nfce config --bind 0.0.0.0 --porta 9155 ``` 3. Libere a porta no firewall da máquina para a rede interna e aponte cada PDV para `http://IP-DO-SERVIDOR:9155`. 4. Se os PDVs rodam no navegador, autorize a origem deles uma vez: `nfce config --origem https://pdv.suaempresa.com.br`. Cada nota recebe o próximo número da série do Agente, independentemente de qual caixa a pediu; a emissão é serializada (uma nota por vez), então dois caixas nunca recebem o mesmo número. Redes com vários CNPJs: pareie cada empresa no Agente da respectiva loja (ou todas no mesmo, se preferir), e o PDV informa a empresa pelo header `X-Empresa-CNPJ`. ## Segunda instância na mesma máquina `BRASILNFE_DATA_DIR` aponta o Agente para outra pasta de dados, isolando pareamentos, notas e configuração. Serve para testes e para um segundo Agente na mesma máquina (por exemplo, outra empresa com outra porta de API local: `nfce config --porta 9156`). ## Proxy HTTP corporativo A conexão mTLS com a SEFAZ respeita as variáveis padrão (as mesmas do `curl`): `HTTPS_PROXY` (ou `HTTP_PROXY`) com `http://usuario:senha@proxy:porta` e `NO_PROXY` para destinos que saem direto. Só proxy `http://` com túnel CONNECT; o TLS continua ponta a ponta com a SEFAZ e o proxy não vê o conteúdo. O Agente **não lê** o proxy configurado no Windows (WinINet): use as variáveis de ambiente. Sem elas, a conexão é direta. ## Onde ficam os dados | Conteúdo | Caminho | | --- | --- | | Pasta de dados (Windows) | `%APPDATA%\br.com.brasilnfe.agent\` | | Pasta de dados (Linux) | `~/.local/share/br.com.brasilnfe.agent/` | | Pareamentos (sem segredos) | `pairings.json` | | Senha do PFX / PIN | Cofre de senhas do sistema operacional. Sem cofre (servidor Linux): arquivo com permissão `0600` na pasta de dados. | | Preferências da interface | `prefs.json` | | Auditoria de assinaturas | `audit.db` (SQLite) | | Configuração da NFC-e | `nfce/nfce.json` (porta, escuta, origens, modo, série/ambiente por empresa) | | Notas off-line e numeração | `nfce/nfce.db` e uma cópia por nota em `nfce/notas/` | | Pacote fiscal off-line | `nfce/sidecar//` (a ativa e a anterior) | | Configuração fiscal da empresa (sem senhas) | `nfce/snapshot_.json` | | Backups do banco de notas | `Documentos\BrasilNFe Agente\backup-nfce\` (Windows) ou `nfce/backup/` (sem pasta Documentos) | | Atualizações baixadas | `updates//` | | Instalação (Windows) | `%LOCALAPPDATA%\Brasil NFe Agente\` | Interface gráfica e headless leem os **mesmos arquivos**: parear num modo e rodar no outro funciona sem conversão. ## Atualização automática O Agente consulta o Brasil NFe ao subir e a cada 6 horas. Se há versão mais nova para o seu alvo, ele baixa, confere o hash e a assinatura digital do pacote e aplica: - **Windows**: roda o instalador em modo silencioso e reabre o Agente. - **Linux headless e AppImage**: substitui o próprio binário e reinicia (transparente sob systemd). - **`.deb`/`.rpm`**: só avisa; atualize pelo gerenciador de pacotes. Para desligar a aplicação automática (ele passa só a avisar): interruptor **Atualização automática** nas configurações ou `BRASILNFE_AUTO_UPDATE=0` no ambiente. Para forçar: `update check` (consulta) e `update apply` (baixa, verifica e aplica), na CLI, na tela ou no console do painel. ## Desinstalar ou remover uma empresa - **Remover um pareamento**: na tela, o "x" da empresa; na CLI, `brasilnfe-agent unpair CODIGO`. Remove o pareamento e o segredo do cofre; as notas off-line já emitidas continuam no banco local até serem enviadas (elas sobem quando a empresa for pareada de novo). - **Revogar pelo painel** (Configurações › Agente › Revogar): derruba o Agente na hora e invalida o código; assinatura e NFC-e off-line param até novo pareamento. - **Desinstalar**: Windows, "Aplicativos instalados"; Linux, `apt remove brasil-nfe-agente` / `dnf remove` ou apague o AppImage/binário. A pasta de dados não é apagada automaticamente; se houver notas off-line pendentes, envie-as antes (ver [NFC-e off-line](/agente-docs/nfce-offline)).