Resposta rápida: para emitir NFS-e pela API do Emissor Nacional, o seu sistema monta a DPS (Declaração de Prestação de Serviço) em XML, assina com o certificado digital ICP-Brasil do prestador, compacta em GZip, converte para Base64 e envia por HTTPS com autenticação mútua (mTLS) à Sefin Nacional. A resposta traz a NFS-e autorizada e a chave de acesso, que depois serve para consultar, baixar o DANFSe e registrar eventos como o cancelamento.
Desde 01/11/2026, microempresas e empresas de pequeno porte do Simples Nacional emitem a NFS-e pelo padrão nacional. Para quem emite por ERP, sistema próprio ou plataforma SaaS, isso significa trocar a integração antiga com a prefeitura pela API nacional. Este guia mostra o caminho completo, do pré-requisito à produção.
O que você precisa antes de começar
- Certificado digital ICP-Brasil do prestador, normalmente o e-CNPJ A1 (arquivo .pfx). Ele é usado em duas coisas diferentes: assinar o XML e autenticar a conexão mTLS.
- Município do prestador aderido ao Sistema Nacional NFS-e e com os parâmetros de tributação configurados no sistema nacional.
- Código de Tributação Nacional de cada serviço que a empresa presta, além do código NBS quando exigido.
- Acesso ao ambiente de Produção Restrita (homologação), onde você testa sem gerar notas com valor fiscal.
- Leiaute e schemas XSD da versão vigente, publicados no portal da NFS-e Nacional (gov.br/nfse). Use sempre a versão mais recente, que já traz os grupos de IBS e CBS da Reforma Tributária.
Passo a passo da integração
1. Monte a DPS em XML
A DPS é o documento que o prestador envia. Ela reúne identificação (série, número e data de emissão), prestador, tomador, serviço (código de tributação nacional, descrição, município de prestação), valores e tributos. Cada DPS tem um identificador formado a partir do município, do CNPJ, da série e do número, e esse conjunto não pode se repetir.
Valide o XML contra o XSD antes de assinar. A maioria das rejeições de primeira viagem é erro de schema: campo obrigatório ausente, formato de data errado ou elemento fora de ordem.
2. Assine com o certificado do prestador
A assinatura segue o padrão XMLDSig, com referência ao atributo Id da DPS e canonicalização definida no leiaute. Um detalhe comum de quebrar a assinatura: qualquer alteração no XML depois de assinado, inclusive espaços e quebras de linha, invalida o documento.
3. Compacte e codifique
O XML assinado é compactado em GZip e o resultado é convertido em Base64. É esse texto que vai no corpo da requisição, dentro de um JSON.
4. Envie com mTLS
A requisição vai para a Sefin Nacional por HTTPS, apresentando o certificado do prestador na conexão (autenticação mútua). Em PHP, o núcleo da chamada fica parecido com isto:
$xmlAssinado = assinarDps($dps, $certificado);
$payload = json_encode([
'dpsXmlGZipB64' => base64_encode(gzencode($xmlAssinado)),
]);
$ch = curl_init($urlSefin . '/nfse');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_SSLCERT => $caminhoCertPem,
CURLOPT_SSLKEY => $caminhoChavePem,
CURLOPT_RETURNTRANSFER => true,
]);
$resposta = json_decode(curl_exec($ch), true);Os nomes exatos de endpoints e campos estão no manual da API da versão vigente. Confira sempre a documentação oficial antes de ir para produção, porque ela muda por nota técnica.
5. Trate a resposta
Em caso de sucesso, a resposta traz a chave de acesso e o XML da NFS-e gerada, também compactado. Guarde os dois: a chave é o identificador para tudo o que vem depois. Em caso de rejeição, a resposta traz o código e a descrição do erro. Registre a requisição e a resposta completas em log, porque é isso que permite resolver o problema rápido.
6. Consulte, baixe o DANFSe e registre eventos
Com a chave de acesso você consulta a nota, obtém o DANFSe (a representação em PDF) e registra eventos como o cancelamento, que também é um XML assinado e enviado pela API. A substituição de uma nota é feita com uma nova DPS que referencia a nota substituída.
Cuidados que evitam dor de cabeça em produção
- Idempotência: se a conexão cair depois do envio, consulte antes de reenviar. Reenviar a mesma série e número gera rejeição por duplicidade; trocar o número gera nota em dobro.
- Fila e retentativa: o serviço nacional pode ficar instável. Emissão síncrona dentro da tela do usuário trava o faturamento; uma fila com reenvio automático não.
- Vencimento do certificado: avise com antecedência. Certificado vencido para toda a emissão do cliente de uma vez.
- Log completo: XML enviado, resposta, data e hora de cada tentativa.
- Teste em Produção Restrita com os cenários reais do cliente: retenção de ISS, tomador do exterior, cancelamento e substituição.
Perguntas frequentes
Preciso de certificado A1 ou serve o A3?
Para integração automatizada, o A1 é o mais prático, porque fica instalado no servidor. O A3 depende de token ou cartão conectado à máquina, o que inviabiliza a emissão em servidor ou em nuvem.
Quanto tempo leva para integrar?
Depende do sistema atual e dos cenários de tributação dos clientes. Uma integração focada, para um sistema com poucos tipos de serviço, costuma ser bem mais rápida do que adaptar vários webservices municipais diferentes, porque o padrão é único.
Existe biblioteca pronta?
Sim. A iLAB4 publica bibliotecas PHP de NFS-e no padrão nacional no GitHub (github.com/ilab4), que você pode usar e auditar. Se preferir não manter essa camada, também entregamos a integração pronta ou uma API REST única para o seu time consumir.
Quer ajuda para colocar a sua integração em produção? Veja como funciona a integração de NFS-e da iLAB4 ou peça um diagnóstico gratuito.
