Pareamento e certificado
O pareamento é o único cadastro do Agente. Ele liga uma empresa do painel a um certificado que fica na máquina, e é a credencial do Agente para tudo: assinar, emitir NFC-e off-line, sincronizar e receber comandos do painel.
O código de pareamento
- Gerado no painel em Configurações › aba Agente › Gerar código de pareamento. Começa com
bna_e identifica a empresa: é assim que o Agente sabe a qual CNPJ o certificado precisa pertencer (e o PDV nunca precisa ver o código). - Trate como senha. Quem tem o código pode parear um Agente a esta empresa. Não o coloque no sistema de vendas nem em páginas web.
- Gerar novo invalida o anterior. Revogar apaga o código: o Agente pareado é desconectado imediatamente e para de assinar e de emitir off-line até um novo pareamento.
- Uma empresa = um certificado = um código. Um Agente pode ter N empresas (N códigos), cada uma com seu certificado, sua série de NFC-e e seu ambiente.
- Uma empresa conecta de um Agente por vez. Se outro Agente (ou outra instância) se conecta com o mesmo código, o servidor derruba a conexão anterior e ela aparece como "substituída". Isso é intencional: evita dois caixas com a mesma numeração. Para vários caixas, use um servidor de loja.
Quando o servidor usa o Agente
| Situação da empresa no painel | Assinatura dos documentos | NFC-e off-line no PDV |
|---|---|---|
| Sem certificado carregado no servidor e com código de pareamento | Pelo Agente (o servidor não tem a chave) | Sim |
| Com certificado A1 carregado no servidor e com código de pareamento | Pelo servidor, como sempre | Sim (o Agente serve só para isso) |
| Sem código de pareamento | Pelo servidor (exige certificado carregado) | Não |
A aba Agente do painel mostra qual é o uso atual ("assinatura via agente" ou "certificado no servidor; agente só para NFC-e offline").
Com a assinatura pelo Agente, ela só acontece enquanto o Agente está aberto e conectado. Emissões pela API ou pelo painel com o Agente fechado retornam erro de assinatura até ele reconectar (ele reconecta sozinho). Tarefas em segundo plano que precisam assinar sem nenhuma máquina do cliente ligada continuam pedindo o certificado A1 no servidor.
Fontes de certificado
O Agente aceita três fontes. A senha ou PIN nunca fica em arquivo de configuração: vai para o cofre de senhas do sistema operacional ou, sem cofre (Linux headless), para um arquivo com permissão restrita ao usuário.
A1 em arquivo (.pfx / .p12)
- Interface: A1 (arquivo .pfx) › Procurar › senha › Validar certificado.
- CLI:
pair CODIGO --pfx /caminho/certificado.pfx(a senha é pedida no prompt, sem eco; para scripts, variávelBRASILNFE_CERT_SECRET). - Certificados ICP-Brasil gerados com cifras antigas (alguns arquivos da AC Soluti e outras), que muitos programas rejeitam com "unsupported", são aceitos.
- O arquivo continua no caminho informado; o Agente lê dele a cada assinatura. Não mova o arquivo sem parear de novo.
A3 em token ou cartão (PKCS#11)
- Interface: A3 (token PKCS#11) › Procurar o módulo do fabricante (
.dllno Windows, ex.:aetpkss1.dllpara SafeNet;.sono Linux, ex.:libaetpkss.so) › slot (opcional; vazio usa o primeiro token presente) › PIN. - CLI:
pair CODIGO --module CAMINHO_DO_MODULO [--slot N]. - A chave privada fica no dispositivo; o Agente pede a operação ao token a cada assinatura. O token precisa estar conectado sempre que houver emissão.
- Não funciona em VPS/nuvem (precisa do hardware USB físico).
Certificado instalado no Windows (CryptoAPI/CNG)
- Interface: aba Certificado instalado, listada automaticamente com os certificados do repositório pessoal do usuário que têm chave privada. Cobre A1 importado (chave de software; sem PIN) e A3 com minidriver do fabricante (pede o PIN).
- CLI:
pair CODIGO --thumbprint SHA1(thumbprint SHA-1, sem espaços;Get-ChildItem Cert:\CurrentUser\Myno PowerShell lista). - A chave não é exportada: o Agente pede ao próprio Windows para assinar.
- Só no Windows; a opção não aparece no Linux.
Validação antes de salvar
O Agente lê os metadados do certificado (titular, emissor, validade) com a senha/PIN informada e recusa se a senha estiver errada, se o arquivo for inválido, se não houver token no leitor ou se o certificado não pertencer ao CNPJ do código de pareamento ("Certificado de outra empresa"). A validade aparece na lista de empresas; renove antes de vencer (ver o que quebra com certificado vencido).
Como funciona a assinatura remota
Depois de pareado, o Agente mantém uma conexão segura (TLS) por empresa com o Brasil NFe:
- Ao conectar, o Agente se apresenta com o código de pareamento e os dados públicos do certificado (titular, validade); nunca a chave. Status "Conectado".
- Periodicamente envia um resumo de situação (versão, plataforma, máquina, NFC-e, fila) que o painel mostra na aba Agente.
- Quando alguém emite um documento dessa empresa (API, painel, integração), o servidor monta o documento e envia ao Agente apenas o trecho a assinar. O Agente assina com o certificado local, no padrão exigido pela SEFAZ, e devolve a assinatura e o certificado público. Status "Assinando N documentos" (com notificação do Windows, se ativada).
- O servidor completa o documento e pede ao Agente que o entregue à SEFAZ. O Agente abre a conexão com TLS mútuo usando o certificado como identidade e devolve a resposta. Status "Postando na SEFAZ".
- O servidor interpreta o retorno da SEFAZ, grava a nota, gera DANFE e responde a quem pediu, exatamente como no fluxo com certificado no servidor.
Cada assinatura gera um registro de auditoria local (data/hora, empresa, certificado, hash do que foi assinado); nunca o conteúdo.
Conexão com a SEFAZ (mTLS)
- Só endereços oficiais das SEFAZ são aceitos. Qualquer outra URL é recusada: o Agente não serve de proxy genérico com o seu certificado.
- Chaves em token A3 e na loja do Windows são usadas no TLS sem sair do dispositivo.
- O certificado do servidor da SEFAZ é validado contra as raízes do sistema mais as raízes ICP-Brasil embutidas no Agente; assim SEFAZ com certificado ICP-Brasil (SP, SVRS) funcionam mesmo em Linux sem a cadeia instalada.
- Proxy HTTP:
HTTPS_PROXY/HTTP_PROXY/NO_PROXY.
Estados da conexão
| Estado (tela / log) | Significado | O que fazer |
|---|---|---|
| Conectando | Abrindo a conexão com o Brasil NFe. | Aguardar. |
| Conectado - Empresa X | Pronto para assinar. | Nada. |
| Reconectando (tentativa N, próximo em Ns): motivo | Conexão caiu ou o servidor não respondeu; nova tentativa com espera progressiva. | Conferir internet/proxy se persistir. |
| Assinando N documentos | Lote em andamento. | Nada. |
| Postando na SEFAZ | POST mTLS em andamento. | Nada. |
| Erro de certificado: mensagem | Senha/PIN errado, arquivo movido, token ausente, segredo não encontrado no cofre. O Agente não reconecta sozinho. | Corrigir a causa e parear/reiniciar. |
| Substituído | Outra instância assumiu esta empresa (mesmo código em outro Agente). Terminal, sem reconexão automática, para não ficar em ping-pong. | Decidir qual máquina fica; reabrir o Agente que deve valer. |
| Desconectado | Encerrado pelo usuário (remoção do pareamento, encerramento do Agente). | - |
Diagnóstico: sefaz-test
Faz um POST mTLS real numa SEFAZ com o certificado informado, sem pareamento nem servidor, para isolar problemas de rede, TLS ou certificado na máquina do cliente:
Code
envelope.xml é qualquer envelope SOAP válido (uma consulta de status serve). Saída esperada: OK: HTTP 2xx ... seguido do cStat/xMotivo. Em falha, a mensagem diz em que etapa parou (DNS, TCP, TLS, assinatura, HTTP). Aceita --module LIB [--slot N], --thumbprint SHA1 e --timeout S.
No painel: aba Agente
- Pareamento: gerar, gerar novo e revogar o código; status (nenhum agente, código gerado aguardando conexão, agente conectado com o titular do certificado).
- Situação do agente (enviada pelo próprio Agente periodicamente): versão, plataforma, máquina, conectado desde, último sinal, NFC-e ativa/parada, série e próximo número, ambiente, modo (contingência forçada em destaque), pacote fiscal instalado, configuração da empresa sincronizada, fila off-line (pendentes, aguardando SEFAZ, transmitidas, rejeitadas, idade da mais antiga).
- Console do agente: executa de longe os mesmos comandos da CLI. Ver CLI e console remoto.
Problemas comuns
| Sintoma | Causa provável | Solução |
|---|---|---|
| "senha do certificado incorreta ou PFX corrompido" | Senha errada ou arquivo danificado. | Confira a senha; teste o .pfx em outro programa. |
| "Certificado de outra empresa" | O CNPJ do certificado não bate com o do código. | Selecione o e-CNPJ da empresa correta ou gere o código na empresa certa. |
| "nenhum token presente no leitor" / "PIN do token incorreto" | Token desconectado, módulo errado, slot errado, PIN errado. | Conecte o token, confira o módulo do fabricante e o slot. |
| Estado "Substituído" | Outra máquina pareou com o mesmo código. | Use um Agente por empresa; para vários caixas, servidor de loja. |
| "Não foi possível validar com segurança o certificado do servidor da SEFAZ" | Raízes ausentes ou relógio errado. | Windows: Windows Update, reinicie, confira data/hora, instale a cadeia ICP-Brasil. Linux: ca-certificates, data/hora. Se continuar, fale com o suporte e não tente contornar: pode haver interceptação de rede. |
| Emissão pela API falha com erro de assinatura | Agente fechado ou desconectado. | Abra o Agente / confira o serviço; veja o estado na aba Agente. |
| Emissão funciona no escritório mas não na loja | Proxy corporativo. | Configure HTTPS_PROXY/NO_PROXY. |