Autenticação e certificado digital em APIs de consulta de NFS-e
· 5 min de leitura
Toda consulta via API ao Ambiente Nacional é autenticada por certificado digital ICP-Brasil. Não existe consulta programática anônima ou por login e senha simples para esse tipo de acesso.
Por que o certificado é necessário
A autenticação acontece via mTLS (TLS mútuo): tanto o servidor quanto quem consulta apresentam certificado, e o Ambiente Nacional usa isso para confirmar que quem está pedindo os documentos fiscais é, de fato, o CNPJ correspondente: sem certificado válido, a conexão nem se estabelece.
Tipos de certificado aceitos
O certificado digital A1 (arquivo, não em cartão ou token físico) é o mais usado para esse tipo de integração programática, por poder ser carregado diretamente pela aplicação que faz a chamada, diferente do certificado A3, pensado para uso interativo (assinatura manual), não para automação de chamadas de API.
Cuidados de segurança
O certificado dá acesso aos documentos fiscais do CNPJ: deve ser armazenado criptografado, nunca em texto puro, com acesso restrito a quem realmente precisa dele. Vencimento também é um ponto de atenção prático: um certificado vencido faz a integração parar de funcionar sem aviso prévio, então vale monitorar a data de expiração com antecedência.
Perguntas frequentes
O certificado da empresa pode ser compartilhado entre sistemas?
Tecnicamente sim, mas cada sistema que carrega o certificado é mais um ponto onde ele precisa ser protegido: quanto mais cópias, maior a superfície de risco. Vale avaliar se cada sistema realmente precisa do certificado, ou se uma integração central que já consulta e distribui os dados resolve sem multiplicar cópias do certificado.
Um erro de autenticação sempre significa certificado inválido?
Não necessariamente: pode ser certificado vencido, certificado do CNPJ errado, ou um problema de configuração na cadeia de confiança. Veja mais em erros e códigos de retorno comuns em APIs de notas fiscais.
Antes de integrar, vale revisar também o que considerar antes de integrar uma API de NFS-e recebidas. Na IntegroBR NFS-e Recebidas, o certificado é enviado uma única vez, extraído e mantido criptografado, sem que sua aplicação precise carregar e gerenciar o arquivo do certificado diretamente.