API do Emissor Nacional da NFS-e: o que precisa para integrar
Equipe GereNota · atualizado em 19/10/2026 · fontes conferidas no texto oficial
Em 30 segundos: O Sistema Nacional da NFS-e tem APIs gratuitas: a Sefin Nacional emite, consulta e registra os eventos, como o cancelamento; o Ambiente de Dados Nacional (ADN) distribui as notas e publica a parametrização dos municípios. A conexão exige o certificado ICP-Brasil da própria empresa (mTLS), e a nota parte de uma DPS em XML assinada, no leiaute nacional. Há um ambiente de testes, a produção restrita.
As duas APIs
| API | Para quê | Produção | Testes (produção restrita) |
|---|---|---|---|
| Sefin Nacional | Emitir a nota, consultar pela chave, registrar eventos (o cancelamento) e conferir uma DPS pelo Id | sefin.nfse.gov.br/SefinNacional | sefin.producaorestrita.nfse.gov.br/SefinNacional |
| ADN, o Ambiente de Dados Nacional | Distribuir as notas e os eventos por NSU, a parametrização dos municípios (alíquotas, retenções e convênio) e o cadastro (CNC) | adn.nfse.gov.br | adn.producaorestrita.nfse.gov.br |
Os manuais, os leiautes (os Anexos), os esquemas XSD e as notas técnicas estão na documentação técnica do gov.br/nfse. A documentação interativa (Swagger) de cada API fica na produção restrita (FAQ, item 19.5).
O que a integração precisa
- O certificado da própria empresa. A conexão é mTLS, e a DPS vai assinada com o certificado ICP-Brasil (e-CNPJ ou e-CPF) do próprio prestador. Não há procuração eletrônica: quem integra várias empresas assina e conecta com o certificado de cada uma (FAQ, item 17.7).
- A DPS no leiaute nacional. A Declaração de Prestação de Serviço é um XML que segue o Anexo I e o esquema XSD v1.01, assinado em XMLDSig e sem prefixo de namespace (o prefixo é recusado, a E1228). Ela vai compactada em GZip e codificada em Base64, num JSON.
- A resposta é síncrona. A emissão (
POST /nfse) devolve a NFS-e autorizada na mesma resposta, com a chave de acesso de 50 dígitos. - A numeração é sua. A série e o número da DPS são do emissor e entram no Id assinado. A série dos aplicativos próprios e da API vai de 00001 a 49999 (FAQ, item 18.1). A consulta pelo Id (
/dps/{id}) diz se aquele número já virou nota, o que evita a nota em dobro numa nova tentativa. - Os eventos. O cancelamento é um evento assinado, com o motivo (
POST /nfse/{chave}/eventos). A substituição é uma DPS nova com o grupo de substituição, que cancela a anterior pelo vínculo. - O PDF é seu. A API oficial do DANFSE foi suspensa em 03/08/2026: quem emite gera o PDF no leiaute da NT 008. O documento fiscal é o XML.
- As regras de validação. O Anexo I traz centenas de regras, e a recusa volta com o código (E0xxx). Valide no XSD antes de enviar e confira as regras do seu caso: o Simples, a retenção, a obra e o evento.
- A parametrização do município. As alíquotas, as retenções e o convênio de cada município ficam no ADN, e a Sefin valida a DPS por eles.
- As mudanças. O leiaute muda por notas técnicas: a da reforma tributária (a NT 004) está em produção desde janeiro de 2026, e a NT 009, com o IBS e a CBS do Simples, está publicada, com a data de produção a confirmar.
O custo de integrar direto
A API é gratuita. O custo é construir e manter: o certificado de cada empresa, a assinatura, o leiaute e as regras, a numeração, o PDF, a distribuição das notas e as mudanças de cada nota técnica.
Uma API por cima da oficial
Um emissor privado pode expor uma API mais simples e cuidar do resto. É o caso do GereNota, no quadro abaixo.
A API do GereNota é REST, em JSON e sem XML: POST /companies/{id}/nfse emite pela API oficial, com o certificado da empresa guardado criptografado. A assinatura, a numeração e o PDF da NT 008 ficam por conta do GereNota. Com "ambiente": "teste", a nota é validada no Sistema Nacional sem efeito fiscal; o cabeçalho Idempotency-Key faz a mesma chamada, em até 24 horas, devolver a mesma nota; e os erros vêm com código, mensagem e dica em português. O guia é público, em gerenota.com.br/api, e a API vem nos planos pagos, a partir do Plano Individual.
Perguntas frequentes
A API do Emissor Nacional é paga?
Não. O custo é o da integração: construir e manter.
Preciso de certificado A1?
De um certificado ICP-Brasil da própria empresa. Num servidor, na prática, usa-se o A1 (o arquivo), porque o A3 fica num cartão ou token.
Tem ambiente de testes?
Sim, a produção restrita, com a documentação interativa (Swagger) de cada API (FAQ, item 19.5). As notas de lá não têm valor fiscal.
Posso emitir para vários clientes com um certificado só?
Não. A assinatura e o mTLS são do próprio prestador, e a nota assinada por outro certificado é recusada (a E0718; FAQ, item 17.7).
Fontes
- Documentação técnica da NFS-e: os manuais, os Anexos e os XSD
- FAQ oficial da NFS-e, v1.1, itens 17.7, 18.1 e 19.5
- NT 008 v1.02, o DANFSE
- NT 009 v1.01, o IBS e a CBS
- Lei Complementar 123/2006, art. 18-A, § 20
- O guia da API do GereNota
Este guia é informativo e não substitui a orientação do seu contador.