API NFS-e Nacional: Guia Prático de Integração REST JSON no SNNFSE (2026)

A emissão de Nota Fiscal de Serviço Eletrônica (NFS-e) sempre foi um dos maiores pesadelos de engenharia de software no Brasil. Com mais de 5.570 municípios, cada prefeitura historicamente adotou seu próprio provedor de mensageria (DSF, Ginfes, Betha, ISSNet, WebISS, Tiplan, Governa, além dos sistemas próprios de São Paulo, Rio de Janeiro e Barueri), exigindo centenas de schemas XML divergentes, certificados mTLS e endpoints SOAP instáveis.

Com a consolidação do Sistema Nacional da NFS-e (SNNFSE) e do Ambiente de Dados Nacional (ADN) pela Receita Federal, o Brasil deu um passo crucial rumo à padronização. Hoje, milhares de municípios já aderiram ao convênio nacional ou estão em fase de homologação.

📌 Guias Especializados do Ecossistema NFS-e:

• 🗺️ API de NFS-e com Cobertura Nacional: Como Emitir em 4.782+ Cidades: Visão completa da malha de 4.782 municípios ativos (SNNFSE + legados).
• 💰 Desconto Condicionado vs Incondicionado na NFS-e: Regras da Portaria 43 de Curitiba e cálculo exato de ISSQN sem autuação.
• ✂️ API NFS-e para Salão Parceiro (Lei 13.352/2016): Dedução legal da cota de profissionais na DPS Nacional e multi-CNPJ.

Neste guia técnico definitivo, você entenderá como funciona a arquitetura do SNNFSE, os gargalos de tentar integrar diretamente com o governo, e como utilizar a API REST da Notaas para emitir NFS-e Nacional com um único payload JSON unificado, retorno assíncrono via webhooks seguros e geração local do DANFSe v2.0.

🏛️ A Arquitetura da NFS-e Nacional (SNNFSE / ADN)

Para entender a integração, é fundamental compreender a separação entre os conceitos do padrão nacional:

🔄 Fluxo de Integração da NFS-e Nacional:

• 1. Seu Backend / SaaS: Envia o payload unificado em JSON via POST /api/v1/emitir.
• 2. Notaas API Gateway: Normaliza os dados, assina o XMLDSig com certificado A1 e conecta ao SNNFSE ou prefeitura legada.
• 3. Autorização Assíncrona: A autoridade fiscal processa e retorna o número da nota e chave única de 50 dígitos.
• 4. Entrega Automática: A Notaas gera o DANFSe v2.0 com QR Code e notifica seu webhook com os links do PDF e XML prontos.

1. DPS vs NFS-e

• DPS (Declaração de Prestação de Serviços): É o documento de declaração enviado pela sua aplicação contendo os dados do prestador, tomador e serviço. O DPS ainda não possui valor fiscal de quitação tributária.
• NFS-e (Nota Fiscal de Serviço Eletrônica): É o documento gerado e assinado pela autoridade tributária (SNNFSE ou prefeitura) após a validação das regras de negócio do DPS, contendo o número da nota, código de verificação e a chave de acesso única de 50 dígitos.

2. Os Gargalos da Integração Direta com a Receita Federal

Muitas equipes tentam construir uma integração direta com os web services do SNNFSE e esbarram em complexidades críticas:

1. Autenticação mTLS Rigorosa: Cada requisição exige um handshake TLS bidirecional com certificado ICP-Brasil A1 (X.509), exigindo gerenciamento complexo de chaves privadas e renovações nos servidores de aplicação.
2. Assinatura XMLDSig Envelope: A Receita Federal exige canonicalização XML (C14N) e assinatura digital com algoritmo SHA-256 e RSA no padrão XMLDSig, processo propenso a erros de codificação de caracteres e tags.
3. Municípios Não-Conveniados: Embora o SNNFSE cresça, prefeituras de grande porte continuam exigindo seus próprios padrões legados. Uma integração direta não resolve o problema multi-cidade da sua empresa.
4. Instabilidade e Filas Assíncronas: A recepção no ADN é frequentemente assíncrona. Se o seu backend fizer polling constante, sofrerá rate-limiting (HTTP 429) ou timeouts de conexão.

📚 Referências Oficiais & Guias Técnicos:

• 🌐 API de Nota Fiscal: Motor unificado para emissão e gestão de NFS-e, NF-e e NFC-e via REST API.
• ⚡ API NFS-e Nacional: Guia prático de integração técnica com o padrão nacional da Receita Federal.
• 📦 API NF-e (Modelo 55): Emissão simplificada de nota fiscal de produto com DANFE em PDF.
• 🛒 API NFC-e (Modelo 65): Automação de cupom fiscal para varejo e PDV com QR Code v2.
• 📄 DANFSe v2.0 em PDF: Geração local de DANFSe e conformidade com a NT-008 sem o visualizador do ADN.
• ⚖️ Comparativo de APIs Fiscais: Análise comparativa entre Notaas, Nuvem Fiscal, Focus NFe e TecnoSpeed.

🚀 A Solução Unificada: Como a Notaas Simplifica o Processo

A Notaas atua como uma camada de abstração de alta performance:

• Payload JSON Padronizado: Os mesmos campos funcionam para o SNNFSE Nacional, Barueri, DSF, Ginfes ou qualquer prefeitura do Brasil.
• Gerenciamento de Certificado A1 em Nuvem: Seus certificados são armazenados em cofres criptografados (KMS HSM).
• Fila de Resiliência Automática: Falhas temporárias da prefeitura ou do SNNFSE são tratadas com retentativas automáticas exponenciais com jitter.
• Geração Instantânea de DANFSe v2.0: O PDF da nota fiscal com QR Code oficial é gerado localmente em menos de 500ms, sem depender da API ADN do governo.

📡 Payload Unificado de Emissão (JSON)

Para emitir uma NFS-e Nacional, basta fazer uma requisição POST para o endpoint /api/v1/emitir:

Endpoint:

POST https://platform.notaas.com.br/api/v1/emitir

Headers:

Content-Type: application/json
X-API-Key: sk_live_sua_chave_secreta_aqui

Corpo da Requisição (Payload JSON):

{
  "tipo": "nfse",
  "ambiente": "producao",
  "referencia": "fatura_saas_2026_9871",
  "prestador": {
    "cnpj": "12345678000195",
    "inscricaoMunicipal": "1234567"
  },
  "tomador": {
    "cpfCnpj": "98765432000109",
    "razaoSocial": "Tech Solutions Brasil Ltda",
    "email": "financeiro@techsolutions.com.br",
    "endereco": {
      "logradouro": "Avenida Paulista",
      "numero": "1000",
      "complemento": "Andar 15",
      "bairro": "Bela Vista",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "01310100"
    }
  },
  "servico": {
    "codigoTributacaoNacional": "010701",
    "codigoTributacaoMunicipio": "010701",
    "discriminacao": "Licenciamento de software SaaS B2B - Mensalidade Ref. Setembro/2026",
    "valorServicos": 1500.00,
    "aliquota": 2.00,
    "retencaoIss": false,
    "codigoMunicipioIncidencia": "3550308",
    "itens": [
      {
        "descricao": "Assinatura Plano Enterprise",
        "quantidade": 1,
        "valorUnitario": 1500.00
      }
    ]
  }
}

Resposta Síncrona Imediata (Enfileiramento HTTP 202):

{
  "id": "nfse_98b7c6d5e4f3a210",
  "status": "processing",
  "tipo": "nfse",
  "referencia": "fatura_saas_2026_9871",
  "createdAt": "2026-09-04T21:45:00.000Z",
  "mensagem": "Nota fiscal enfileirada para transmissão junto ao SNNFSE."
}

💻 Implementação Prática em Código

1. Chamada via cURL

curl -X POST https://platform.notaas.com.br/api/v1/emitir   -H "Content-Type: application/json"   -H "X-API-Key: sk_test_seu_token"   -d '{
    "tipo": "nfse",
    "ambiente": "sandbox",
    "referencia": "doc_teste_01",
    "prestador": { "cnpj": "12345678000195" },
    "tomador": {
      "cpfCnpj": "00000000000191",
      "razaoSocial": "Tomador Teste Ltda",
      "email": "teste@notaas.com.br"
    },
    "servico": {
      "codigoTributacaoNacional": "010701",
      "discriminacao": "Consultoria em arquitetura de microsserviços",
      "valorServicos": 500.00,
      "aliquota": 2.0
    }
  }'

2. Integração em TypeScript / Node.js

import axios from "axios";

interface EmitirNFSePayload {
  tipo: "nfse";
  ambiente: "sandbox" | "producao";
  referencia: string;
  prestador: { cnpj: string; inscricaoMunicipal?: string };
  tomador: {
    cpfCnpj: string;
    razaoSocial: string;
    email: string;
    endereco?: {
      logradouro: string;
      numero: string;
      bairro: string;
      codigoMunicipio: string;
      uf: string;
      cep: string;
    };
  };
  servico: {
    codigoTributacaoNacional: string;
    discriminacao: string;
    valorServicos: number;
    aliquota: number;
    retencaoIss?: boolean;
    codigoMunicipioIncidencia?: string;
  };
}

export async function emitirNfseNacional(dados: EmitirNFSePayload) {
  try {
    const response = await axios.post(
      "https://platform.notaas.com.br/api/v1/emitir",
      dados,
      {
        headers: {
          "Content-Type": "application/json",
          "X-API-Key": process.env.NOTAAS_API_KEY!,
        },
        timeout: 10000,
      }
    );
    return response.data;
  } catch (error: any) {
    console.error("Erro na emissão NFS-e:", error.response?.data || error.message);
    throw error;
  }
}

3. Integração em Python 3 (FastAPI / Django)

import os
import requests
from pydantic import BaseModel, Field

NOTAAS_API_KEY = os.getenv("NOTAAS_API_KEY")
API_URL = "https://platform.notaas.com.br/api/v1/emitir"

def emitir_nfse(referencia: str, cnpj_prestador: str, cliente_doc: str, razao_social: str, valor: float):
    payload = {
        "tipo": "nfse",
        "ambiente": "producao",
        "referencia": referencia,
        "prestador": {"cnpj": cnpj_prestador},
        "tomador": {
            "cpfCnpj": cliente_doc,
            "razaoSocial": razao_social
        },
        "servico": {
            "codigoTributacaoNacional": "010701",
            "discriminacao": "Serviços de desenvolvimento de software customizado",
            "valorServicos": valor,
            "aliquota": 2.5,
            "retencaoIss": False
        }
    }

    headers = {
        "Content-Type": "application/json",
        "X-API-Key": NOTAAS_API_KEY
    }

    response = requests.post(API_URL, json=payload, headers=headers, timeout=15)
    response.raise_for_status()
    return response.json()

🔒 Recebendo Notificações via Webhooks com Assinatura HMAC

Como a autorização tributária pode levar de 1 a 15 segundos dependendo da fila do SNNFSE, a Notaas notifica seu sistema via Webhook. Cada requisição contém o cabeçalho x-notaas-signature gerado via HMAC SHA-256 para você validar que a mensagem veio legitimamente da Notaas.

Exemplo de Rota Next.js App Router (app/api/webhooks/notaas/route.ts):

import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";

export async function POST(req: NextRequest) {
  const signature = req.headers.get("x-notaas-signature");
  const rawBody = await req.text();
  const secret = process.env.NOTAAS_WEBHOOK_SECRET!;

  // 1. Verificação de segurança criptográfica
  const computedHash = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  if (!signature || !crypto.timingSafeEqual(Buffer.from(computedHash), Buffer.from(signature))) {
    return NextResponse.json({ error: "Assinatura inválida" }, { status: 401 });
  }

  const event = JSON.parse(rawBody);

  // 2. Processamento do evento
  switch (event.event) {
    case "nfse.issued":
      console.log(`✅ NFS-e emitida com sucesso: Nota Nº ${event.data.numero}`);
      console.log(`Chave de Acesso (50 dígitos): ${event.data.chaveAcesso}`);
      console.log(`Link DANFSe PDF: ${event.data.pdfUrl}`);
      console.log(`Link XML Oficial: ${event.data.xmlUrl}`);
      // Salvar links no banco de dados e atualizar status da fatura
      break;

    case "nfse.rejected":
      console.error(`❌ Erro de validação municipal/nacional: ${event.data.motivoRejeicao}`);
      // Notificar cliente ou operador interno
      break;

    case "nfse.cancelled":
      console.log(`⚠️ NFS-e cancelada: ${event.data.numero}`);
      break;
  }

  return NextResponse.json({ success: true });
}

📄 Geração do DANFSe v2.0 e o Fim do Visualizador ADN

Em 2026, a Receita Federal confirmou o desligamento do visualizador público online (API ADN). Desenvolvedores que apenas redirecionavam seus clientes para a URL pública do governo federal enfrentam quebras de links e páginas em branco.

Com a Notaas, o layout do DANFSe v2.0 (padronizado pela Nota Técnica NT-008) é compilado diretamente pela nossa infraestrutura:

• O PDF é gerado em menos de 500 milissegundos.
• O QR Code de autenticação é renderizado de acordo com as diretrizes do Comitê Gestor.
• Os arquivos PDF e XML são distribuídos através de CDNs com links assinados e armazenamento de longo prazo garantido por 5 anos (conforme exigência fiscal do CTN).

📊 Tabela de Correspondência: DPS vs NFS-e

⚖️ A Reforma Tributária 2026 e o Impacto na NFS-e

A partir de 2026, tem início o período de teste e transição da Reforma Tributária sobre o Consumo (EC 132/2023), que unificará o ISS e o ICMS no IBS (Imposto sobre Bens e Serviços) e criará a CBS (Contribuição sobre Bens e Serviços) federal.

O padrão NFS-e Nacional foi desenvolvido exatamente para suportar a segregação do IBS e da CBS. A API da Notaas já possui suporte aos campos tributários adicionais de teste exigidos na Nota Técnica 2025.002, permitindo que seu SaaS esteja 100% em conformidade com o novo regime fiscal brasileiro sem a necessidade de reescrever seu código.

❓ Perguntas Frequentes (FAQ)

1. O MEI (Microempreendedor Individual) é obrigado a emitir pelo padrão nacional?

Sim. Desde setembro de 2023, todos os MEIs do Brasil são obrigados a emitir suas notas fiscais de serviço exclusivamente através da plataforma nacional da NFS-e. A Notaas oferece suporte completo à emissão de NFS-e para MEIs com simplificação tributária.

2. Qual a diferença entre o código de tributação municipal e nacional?

O código municipal varia em cada cidade de acordo com o Código Tributário Municipal (CTM). Já o código nacional (codigoTributacaoNacional) segue uma tabela unificada mantida pela Receita Federal, correspondente aos subitens da Lei Complementar nº 116/2003. A Notaas realiza o de-para automático dessas tabelas sempre que aplicável.

3. Preciso de certificado digital A1 para emitir em Sandbox?

Não. No ambiente de Sandbox da Notaas, você pode simular emissões, testar rejeições de validação e disparar webhooks sem a necessidade de fazer upload de um certificado real. Para produção, é exigido um certificado digital ICP-Brasil A1 no formato .pfx ou .p12.

4. Como resolver o "Erro ao gerar chave da NFS-e — falha de conexão com a API do integrador nfse-nacional"?

Esse erro ocorre quando os servidores da Sefin Nacional (sefin.nfse.gov.br) ou do ADN (adn.nfse.gov.br) sofrem instabilidade no handshake mTLS ou timeout na consulta do convênio municipal. Veja nosso guia técnico passo a passo para resolver a falha de conexão na API do integrador NFS-e Nacional com filas assíncronas, Idempotency-Key e geração local do DANFSe v2.0.

5. Guias Avançados do Cluster NFS-e Nacional (Casos Específicos):

• 👤 Prestador Pessoa Física (CPF e CAEPF) na NFS-e Nacional: Como gerar o TSIdDPS com tpInscr=1, enviar <CPF> e <CAEPF> e cancelar com <CPFAutor>.
• 🏗️ Erros E0903 e E0932 no IBS/CBS (<imovel>, <tpOper> e <gRefNFSe>): Condicionalidade entre obra e imóvel e diferenças entre os 3 leiautes XSD (nt004, nt009 e notacontrol).
• 🏛️ Provedores Híbridos do Padrão Nacional (Pronim/Cidade360, SpeedGov e ISSNet Nacional): Como resolver os erros E376 (<DadosDPS>), E0617 e o cancelamento e101103 em Goiânia e Brasília.
• 🗺️ NFS-e Equiplano no Paraná, Cuiabá (ISSNet Nacional) e Erros E166, E390 e E400 no SpeedGov: Integração SOAP/mTLS para 20 municípios do PR, Cuiabá/MT e separação de RegimeEspecialTributacao vs DadosDPS.RegEspTrib.
• 🔤 CNPJ Alfanumérico em 2026 (IN RFB 2.229 e NT-009): Cálculo do DV Módulo 11 ASCII em TypeScript e impacto nas chaves de 44 e 50 posições.
• 🤖 MCP Server de Nota Fiscal (@notaas/mcp v0.2.2 com 46 Tools): Emita NFS-e e gerencie múltiplos CNPJs diretamente pelo Claude Code, Cursor e Windsurf.

🚀 Comece a Integrar a NFS-e Nacional Hoje Mesmo

Pare de perder tempo lidando com dezenas de provedores municipais e schemas XML complexos. Automatize seu faturamento com a API mais moderna do mercado:

👉 Criar Conta Gratuita na Notaas (20 Notas/Mês Sem Cartão)
👉 Consultar a Documentação Técnica Interativa
👉 Comparativo: Veja Como a Notaas Supera APIs Tradicionais