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.
📌 Cobertura Nacional Abrangente: Para entender os detalhes de emissão em mais de 4.782 municípios unificando o Sistema Nacional e provedores legados municipais, confira nosso guia aprofundado: API de NFS-e com Cobertura Nacional: Como Emitir em 4.782+ Cidades.
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:
- 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.
- 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.
- 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.
- 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
| Campo no Payload Notaas | Tag no Schema SNNFSE (XML) | Descrição e Validação |
|---|---|---|
servico.codigoTributacaoNacional |
<cTribNac> |
Código de 7 dígitos da LC 116/2003 (ex: 010701 para suporte técnico) |
servico.codigoMunicipioIncidencia |
<cMunIncid> |
Código IBGE do município onde ocorreu a prestação do serviço (7 dígitos) |
prestador.inscricaoMunicipal |
<imPrest> |
Inscrição municipal do prestador cadastrada na prefeitura de origem |
tomador.cpfCnpj |
<CNPJ> ou <CPF> |
Documento do tomador (validação algorítmica de dígitos verificadores) |
servico.retencaoIss |
<issRetido> |
true se o tomador for o responsável tributário pela retenção do ISS |
⚖️ 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.
🚀 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 (50 Notas/Mês Sem Cartão)
👉 Consultar a Documentação Técnica Interativa
👉 Comparativo: Veja Como a Notaas Supera APIs Tradicionais