NFS-e Nacional: O Guia Definitivo para Desenvolvedores Integrarem o Padrão ADN do Gov.br

1. O Cenário Antes do Padrão Nacional

Se você já integrou NFS-e municipal, sabe do que estou falando:

• Cada município, um XML diferente — alguns usavam ABRASF 2.01, outros 2.02, 2.03, ou padrão próprio
• SOAP municipal — sim, SOAP em pleno 202X
• Timeout síncrono — requests que travavam o ERP por minutos
• Homologação por CPF — precisava de CPF do contador pra testar
• Sem webhook — o famoso "deu erro? tenta de novo daqui 5 minutos"

E o pior: se você atendia clientes em múltiplos municípios, precisava manter N integrações diferentes.

2. O Padrão Nacional (ADN/gov.br)

A partir da Resolução do Comitê Gestor do Simples Nacional (CGSN), a NFS-e Nacional unificou o processo:

2.1 O que é a DPS?

A DPS (Documento de Prestação de Serviço) é o XML que substituiu os antigos RPS municipais. Ela segue o XSD oficial v1.01 e contém:

<DPS xmlns="http://www.sped.fazenda.gov.br/nfse" versao="1.01">
  <infDPS Id="DPS202606...">
    <tpAmb>1</tpAmb>           <!-- 1 = produção, 2 = homologação -->
    <dhEmi>2026-06-15T14:30:00-03:00</dhEmi>
    <serie>00001</serie>
    <nDPS>1042</nDPS>
    <cLocEmi>3550308</cLocEmi>

    <!-- Prestador (CNPJ do emitente) -->
    <prest>
      <CNPJ>26361810000167</CNPJ>
      <IM>12345</IM>
    </prest>

    <!-- Tomador -->
    <toma>
      <CNPJ>12345678000195</CNPJ>
      <xNome>Cliente Exemplo LTDA</xNome>
    </toma>

    <!-- Serviço -->
    <serv>
      <cServ>01.03.02</cServ>
      <vServ>15000.00</vServ>
      <vIss>150.00</vIss>
    </serv>
  </infDPS>
</DPS>

2.2 Por que mTLS?

O gov.br exige autenticação mútua via TLS (mTLS). Isso significa que:

• O servidor (SEFIN) se apresenta com um certificado válido
• Você também precisa se apresentar com seu certificado A1
• A conexão é criptografada e mutuamente autenticada

Na prática, você precisa de um certificado A1 (arquivo .pfx) por CNPJ estabelecimento.

3. Arquitetura de uma Integração Robusta

┌─────────────┐     POST /nfse      ┌──────────────┐    mTLS     ┌──────────┐
│   Seu ERP   │  ──────────────────►│  API NFS-e   │────────────►│  SEFIN   │
│  (sistema)  │                     │   (Blit)     │◄────────────│ (gov.br) │
└──────┬──────┘                     └──────┬───────┘    mTLS     └──────────┘
       │                                   │
       │  202 Accepted + id da nota        │
       │◄──────────────────────────────────│
       │                                   │
       │  Webhook: issued / cancelled      │
       │◄──────────────────────────────────│
       │                                   │
       │  GET /nfse/{id} (polling)         │
       │◄──────────────────────────────────│

3.1 Por que assíncrono é melhor?

O fluxo síncrono municipal era um pesadelo:

• Se o município demorasse 15s pra responder, seu request travava
• Se desse timeout, você não sabia se a nota foi emitida ou não
• Você precisava de curl com timeout alto e retry manual

O fluxo assíncrono resolve isso:

1. Você POST /nfse e recebe HTTP 202 + o id da nota
2. A emissão vai pra fila e é processada em background
3. Você recebe um webhook assinado quando a nota é emitida (ou rejeitada)
4. Opcionalmente, faz polling em GET /nfse/{id}

3.2 Idempotência é obrigatória

Seu ERP pode tentar emitir a mesma nota duas vezes (retry por timeout de rede). Sem idempotência, você emite a nota em dobro.

POST /api/v1/nfse
Idempotency-Key: erp-pedido-991
Content-Type: application/json

{
  "taker_cnpj": "12345678000195",
  "service_amount": 150.00,
  "service_code": "01.03.02",
  "emit_now": true
}

Se você repetir a mesma Idempotency-Key, a API retorna a mesma nota — sem duplicar.

4. Pontos de Dor Comuns e Como Evitá-los

5. Mão na Massa: Emitindo sua Primeira Nota

# 1. Crie sua conta grátis (5 notas/mês)
#    → https://nfe.blit.app.br/register
#
# 2. Suba seu certificado A1 no painel
#
# 3. Gere um token de API (scope: emit)
#
# 4. Emita sua primeira nota:

curl -X POST https://api.nfe.blit.app.br/api/v1/nfse \
  -H "Authorization: Bearer nft_se…aqui" \
  -H "Idempotency-Key: minha-primeira-nota-001" \
  -H "Content-Type: application/json" \
  -d '{
    "taker_cnpj": "12345678000195",
    "taker_razao": "Cliente Exemplo LTDA",
    "service_code": "01.03.02",
    "service_amount": 1500.00,
    "service_description": "Desenvolvimento de módulo fiscal",
    "emit_now": true
  }'

# Resposta: HTTP 202
# {
#   "async": true,
#   "data": { "id": 42, "status": "pending" }
# }

Em segundos, você recebe o webhook issued com o XML autorizado e o PDF da DANFSe.

6. Checklist para Escolher uma API de NFS-e

7. Conclusão

O padrão NFS-e Nacional (ADN/gov.br) veio pra simplificar — mas ainda tem complexidade técnica que uma boa API resolve: certificado A1, mTLS, DPS, webhooks, idempotência.

Se você está construindo um sistema que precisa emitir notas fiscais de serviço, não faz sentido implementar tudo isso do zero. Use uma API especializada e foque no que importa: seu produto.

Publicado por Blit Softwares e Tecnologia Digital LTDA · CNPJ 26.361.810/0001-67