Resumo: os webservices da SEFAZ (NF-e, CT-e, MDF-e e Distribuição DF-e) e a API da NFS-e Nacional exigem autenticação mútua (mTLS) com o certificado digital ICP-Brasil da empresa. Na prática, muitos ambientes de hospedagem têm dificuldade com isso, principalmente com arquivos PFX antigos. Uma solução que uso é um proxy mTLS dedicado: ele recebe o envelope da requisição, monta a conexão com o certificado em memória e devolve a resposta da SEFAZ, sem gravar o certificado em disco.
Neste artigo
O que é mTLS e por que a SEFAZ exige
Em uma conexão HTTPS comum, só o servidor apresenta certificado. No mTLS (mutual TLS), o cliente também se identifica com um certificado digital durante o handshake. É assim que a SEFAZ sabe, antes mesmo de ler o XML, qual empresa está chamando o serviço.
Esse certificado é o e-CNPJ ICP-Brasil da empresa, normalmente do tipo A1, distribuído como arquivo .pfx (PKCS#12) protegido por senha. O mesmo certificado também é usado para assinar digitalmente os XMLs de documentos e eventos. São duas camadas diferentes: o mTLS protege o transporte, a assinatura garante a autoria do documento.
| Serviço | Formato | Autenticação |
|---|---|---|
| NF-e e NFC-e (autorização, consulta, eventos) | SOAP 1.2 sobre HTTPS | mTLS com certificado ICP-Brasil |
| CT-e e MDF-e | SOAP 1.2 sobre HTTPS | mTLS com certificado ICP-Brasil |
| Distribuição DF-e | SOAP 1.2 sobre HTTPS | mTLS com certificado ICP-Brasil |
| NFS-e Nacional | API REST com JSON | mTLS com certificado ICP-Brasil |
Por que um proxy mTLS dedicado
Na teoria, qualquer linguagem consegue fazer uma requisição com certificado de cliente. Na prática, aparecem obstáculos que travam projetos:
- Hospedagens compartilhadas com pouco controle sobre OpenSSL e bibliotecas de rede.
- Arquivos PFX antigos gerados com algoritmos legados, que versões recentes do OpenSSL recusam por padrão.
- Necessidade de gravar certificado e chave em arquivos temporários só para fazer a chamada.
- Vários sistemas, em linguagens diferentes, repetindo a mesma lógica de conexão.
- Dificuldade de padronizar tempo limite, logs e tratamento de erro de rede.
O proxy concentra esse problema em um só lugar. Desenvolvi um serviço em Node.js com duas rotas: uma para os webservices SOAP da SEFAZ e outra para a API REST da NFS-e. O sistema de gestão continua montando e assinando o XML; o proxy cuida apenas do transporte com mTLS.
Como o proxy funciona
- O sistema envia ao proxy a URL do webservice, o envelope SOAP já montado e o certificado em Base64 com a senha.
- O proxy abre o PKCS#12 em memória com uma biblioteca que suporta algoritmos legados.
- Extrai a cadeia de certificados e a chave privada no formato PEM, sem gravar nada em disco.
- Abre a conexão HTTPS com certificado de cliente e envia o envelope com
Content-Type: application/soap+xml. - Aplica um tempo limite de 30 segundos para não prender o sistema em uma conexão travada.
- Devolve ao sistema o status HTTP e o corpo da resposta da SEFAZ, sem interpretar o conteúdo fiscal.
POST /sefaz-proxy
{
"url": "https://<webservice-do-autorizador>/NFeAutorizacao4.asmx",
"soapEnvelope": "<soap12:Envelope ...>...</soap12:Envelope>",
"pfxBase64": "<certificado em base64>",
"pfxPassword": "<senha>"
}Para a NFS-e Nacional, a rota equivalente recebe o método HTTP, a URL e o corpo JSON. A conexão usa o mesmo princípio: certificado convertido em memória e chamada com mTLS.
O proxy não é um emissor
Ele não monta XML, não assina documento e não decide regras fiscais. Essa separação é proposital: a lógica fiscal fica no sistema de gestão, versionada junto com as regras do negócio, e o proxy permanece pequeno, fácil de auditar e de manter.
Erros mais comuns e como diagnosticar
| Sintoma | Causa provável | O que verificar |
|---|---|---|
| Falha no handshake TLS | Certificado vencido, revogado ou senha incorreta | Validade, senha e se o PFX contém a chave privada |
| Erro ao abrir o PFX | Algoritmo de proteção legado | Biblioteca com suporte a PKCS#12 antigo ou reexportação do certificado |
| Rejeição de certificado | Cadeia ICP-Brasil incompleta | Certificados intermediários no PFX e na cadeia de confiança |
| Resposta de outro ambiente | Mistura de homologação e produção | URL do webservice e o campo de ambiente do XML |
| Serviço inexistente | Autorizador errado para a UF | Tabela de webservices do autorizador e serviços de contingência |
| Consumo indevido | Excesso de consultas repetidas | Intervalo entre consultas, principalmente na Distribuição DF-e |
| Tempo esgotado | Instabilidade do autorizador | Retentativa controlada e contingência quando aplicável |
Segurança do certificado
O certificado A1 é, na prática, a identidade digital da empresa. Quem tem o arquivo e a senha consegue assinar documentos em nome dela. Por isso, a arquitetura precisa tratar o certificado como o dado mais sensível do sistema:
- Armazenar o certificado e a senha criptografados no banco, nunca em texto puro.
- Manter o proxy em rede interna ou atrás de autenticação e restrição de origem.
- Usar sempre HTTPS entre o sistema e o proxy.
- Não registrar certificado, senha nem envelope completo nos logs.
- Converter o certificado apenas em memória, durante a requisição.
- Monitorar a data de vencimento e avisar com antecedência.
- Restringir quem pode cadastrar ou substituir certificados no painel.
Quando essa arquitetura faz sentido
Ela é útil quando a empresa tem um ERP ou sistema próprio que precisa emitir, consultar ou baixar documentos fiscais, quando há vários CNPJs com certificados diferentes, ou quando o ambiente de hospedagem não oferece controle suficiente sobre TLS. É a base de funcionalidades como o módulo DF-e, que consulta documentos emitidos contra o CNPJ da empresa.
Perguntas frequentes
Certificado A3 funciona nesse modelo?
O A3 fica em token ou cartão e não pode ser exportado como arquivo, então não serve para um proxy em servidor. Para integrações automatizadas, o certificado A1 é o formato adequado.
O proxy armazena o certificado?
Não. Na arquitetura que uso, o certificado é armazenado criptografado no sistema de gestão e enviado ao proxy apenas durante a requisição. O proxy converte o arquivo em memória e não grava nada em disco.
Preciso de um proxy se meu servidor já faz mTLS?
Não necessariamente. Se o ambiente controla bem OpenSSL, certificados e tempo limite, a chamada pode ser feita direto. O proxy é útil para padronizar várias aplicações e contornar limitações do ambiente.
A NFS-e também usa certificado?
Sim. A API da NFS-e Nacional usa autenticação mútua com certificado ICP-Brasil. Prefeituras com sistemas próprios podem ter regras diferentes.
Precisa integrar seu sistema à SEFAZ?
Desenvolvo integrações fiscais com mTLS, assinatura de XML, consulta e distribuição de documentos, sempre com certificado protegido, logs e tratamento de erros.