API de NFS-e com Cobertura Nacional: Como Emitir em 4.202+ Cidades, Padrão SNNFSE e Provedores Municipais em um Único Endpoint JSON

Integrar a emissão de Nota Fiscal de Serviços Eletrônica (NFS-e) no Brasil é historicamente um dos maiores desafios de arquitetura de software para qualquer empresa de tecnologia, ERP, plataforma SaaS, fintech ou marketplace. Enquanto a Nota Fiscal Eletrônica de mercadorias (NF-e Modelo 55) possui uma infraestrutura unificada centralizada pelas Secretarias de Fazenda estaduais (SEFAZ), o ecossistema da NFS-e é pulverizado entre 5.571 municípios (5.570 municípios mais o Distrito Federal), onde cada um possui autonomia constitucional para determinar suas próprias alíquotas, regras fiscais, layouts XML e provedores de tecnologia.

Na prática, isso gerou um mosaico de dezenas de provedores de software municipal — como GissOnline, Betha Sistemas, TBW, AtendeNet (IPM), DBSeller, Tinus, Fiorilli, Centi, WebISS, Ginfes, Coplan, ISSNet, DSF, Sigep, Pronim — operando sob contratos proprietários ou versões customizadas e frequentemente incompatíveis do padrão conceitual da ABRASF (Associação Brasileira das Secretarias de Finanças das Capitais).

Neste guia técnico exaustivo, apresentamos a radiografia completa do ecossistema de NFS-e no Brasil em 2026, o avanço da adesão ao Sistema Nacional da NFS-e (SNNFSE / ADN), os dados consolidados da auditoria nacional de municípios e como a Notaas viabiliza a emissão em mais de 4.200 cidades ativas em produção imediata através de um único endpoint REST em JSON, com roteamento dinâmico, resolução inteligente de códigos fiscais e endpoint público de busca de cobertura.

🎯 Resumo Direto para Engenharia (AEO / Snippet para IA)

📌 Como funciona a cobertura nacional unificada de NFS-e via API da Notaas? A plataforma Notaas abstrai a complexidade dos 5.571 municípios brasileiros através de um motor de roteamento inteligente (NfseSystemRouter). A aplicação cliente envia um payload JSON universal para POST /api/v1/emitir. O motor fiscal identifica o município pelo código IBGE de 7 dígitos, determina se a transmissão deve ser feita via REST mTLS para o Sistema Nacional (SNNFSE) ou via SOAP XMLDSig para a engine municipal homologada (24 famílias ativas), resolve automaticamente códigos tributários locais (desdobros municipais versus NBS nacional de 9 dígitos) e entrega o XML autorizado e o DANFSe em PDF v2.0 via webhook assinado com HMAC SHA-256.

🗺️ O Desafio dos 5.571 Municípios Brasileiros: Anatomia do Caos Fiscal

O artigo 156, inciso III, da Constituição Federal de 1988 outorga aos municípios a competência para instituir o Imposto Sobre Serviços de Qualquer Natureza (ISSQN). Como reflexo dessa descentralização política e tributária:

1. Inexistência de um Web Service Centralizador Único no Passado: Historicamente, cada prefeitura abriu licitações para contratar seu próprio fornecedor de sistema tributário, resultando em mais de 70 empresas desenvolvedoras de webservices municipais.
2. Proliferação de Dialetos XML e Incompatibilidade ABRASF: Embora a ABRASF tenha publicado manuais conceituais (versões 1.00, 2.02, 2.03 e 2.04), os fornecedores introduziram interpretações livres de tags obrigatórias, formatos de data (com ou sem timestamp/timezone), namespaces XML divergentes e envelopes SOAP complexos.
3. Criptografia e Conexão Heterogêneas: Algumas prefeituras exigem autenticação mTLS (Mutual TLS com certificado cliente A1), enquanto outras transmitem sem mTLS mas exigem assinatura digital XMLDSig tag a tag no lote de RPS (Recibo Provisório de Serviços) utilizando algoritmos obsoletos como RSA-SHA1 ou modernos como RSA-SHA256.
4. Disparidade de Códigos de Tributação: O que na Prefeitura de São Paulo é o codigoServico de 5 dígitos próprio da capital paulistana (ex: 02800), em capitais como Belo Horizonte ou Curitiba é o item da lista da Lei Complementar nº 116/2003 (ex: 01.07), enquanto cidades sob provedores como TBW, Betha ou AtendeNet exigem a Nomenclatura Brasileira de Serviços (NBS) com 9 dígitos obrigatórios.

Para uma equipe de engenharia em crescimento, integrar e manter conexões ponto a ponto com dezenas de prefeituras significa alocar desenvolvedores seniores em tempo integral apenas para decifrar manuais em PDF de 300 páginas desatualizados, monitorar quedas de webservices instáveis e tratar erros crípticos em linguagens legadas.

📊 O Raio-X da Cobertura Nacional Notaas: Dados Consolidados de Produção

A equipe de engenharia da Notaas realizou uma auditoria técnica rigorosa na base territorial brasileira de 5.571 municípios, cruzando a fonte de verdade do banco de dados de produção (ibge_municipalities.sistema_nfse) com levantamentos de fornecedores de software e disponibilidade de webservices públicos.

A tabela abaixo sintetiza a distribuição consolidada da cobertura no país:

💡 A Regra de Universalidade MEI (Resolução CGSN nº 169/2022): Há um aspecto normativo fundamental que desenvolvedores e contadores precisam dominar: mesmo nos municípios classificados como "sem webservice" ou "aguardando homologação", quando o prestador do serviço for um Microempreendedor Individual (MEI), a cobertura da Notaas é de 100% em todo o território nacional. Por força da Resolução CGSN nº 169/2022, todos os MEIs do país emitem obrigatoriamente pelo Sistema Nacional da NFS-e (SNNFSE / ADN), eliminando qualquer barreira municipal.

⚡ As 24 Famílias de Engines Homologadas na Notaas

A Notaas não apenas conecta municípios, mas normaliza o comportamento fiscal através de 25 identificadores de sistema consolidados em 24 famílias de engines. Cada engine possui drivers customizados de serialização, assinatura criptográfica e sanitização de payloads.

⚡ Fluxo de Integração e Roteamento:

• 1. Aplicação Cliente: Dispara requisição JSON padronizada para POST /api/v1/emitir.
• 2. NfseSystemRouter: Avalia o código IBGE do prestador, o regime tributário (MEI vs. ME/EPP/Normal) e resolve a engine responsável em memória.
• 3. Motor Fiscal Normalizador: Mapeia campos canônicos, converte alíquotas decimais e insere códigos tributários específicos (NBS, item LC 116 ou código municipal).
• 4. Security Engine: Assina o envelope digitalmente com Certificado Digital A1 (PKCS#12) e abre canal seguro (mTLS ou SOAP/XMLDSig).
• 5. Autorização: O webservice municipal ou o ADN autoriza a nota fiscal gerando o número oficial e a chave de acesso.
• 6. Webhook Assinado: A Notaas notifica seu webhook com payload completo, links do XML autorizado e DANFSe em PDF v2.0.

Abaixo, detalhamos o comportamento das principais engines em operação:

1. Sistema Nacional da NFS-e (snnfse / ADN / DFe)

O padrão nacional instituído pela Receita Federal do Brasil (RFB) e administrado pelo Serpro. Opera sob arquitetura REST com payloads JSON ou XML envelopados e comunicação autenticada via mTLS.

• Abrangência: Milhares de municípios conveniados ao Ambiente de Dados Nacional (ADN) e a totalidade dos MEIs do Brasil.
• Particularidade de Payload: Exige o código de tributação nacional estruturado e gera uma chave de acesso de 50 dígitos (semelhante à chave de 44 dígitos da NF-e).
• Vantagem Notaas: Geração local de DANFSe v2.0 em PDF conforme a NT-008, eliminando a dependência do visualizador público instável do ADN.

2. São Paulo Capital (sp_prefeitura)

A maior prefeitura do país opera sistema proprietário desenvolvido pela Prodam, com alto volume de requisições e regras específicas de validação.

• Particularidade de Payload: Exige obrigatoriamente o codigoServico municipal de 5 dígitos (ex: 02800 para software, 02496 para licenciamento).
• Alíquota: A alíquota informada não pode ser inferior ao piso municipal de 2,00%. A prefeitura exige Inscrição Municipal ativa e cálculo rigoroso de retenções na fonte.

3. Engine TBW (tbw)

Presente em polos industriais e logísticos de grande relevância, como Cubatão e Mogi das Cruzes/SP.

• Particularidade de Payload: Exige a NBS (Nomenclatura Brasileira de Serviços) de 9 dígitos obrigatória (servico.nbs), além de validação estrita de endereço completo do tomador do serviço (logradouro, número, bairro, código de município e CEP válidos).
• Conformidade: Totalmente adaptada às diretrizes da Nota Técnica NT 007 para evitar rejeições cadastrais.

4. GissOnline (gissonline)

Um dos provedores pioneiros do Brasil, utilizado em dezenas de cidades de médio porte no estado de São Paulo e Minas Gerais.

• Particularidade de Payload: Exige detalhamento analítico de retenções federais (PIS, COFINS, INSS, IRRF, CSLL) e suporte avançado para deduções de materiais na construção civil.

5. Betha Sistemas (betha)

Fornecedor com vasta presença nas prefeituras das regiões Sul, Sudeste e Centro-Oeste do Brasil.

• Particularidade de Payload: Suporta tanto o padrão ABRASF 1.0 quanto ABRASF 2.0. Exige Inscrição Municipal vinculada e código de tributação municipal com desdobro específico.

6. AtendeNet (atendenet - IPM Sistemas)

Provedor moderno com grande penetração nos estados do Paraná, Santa Catarina e Rio Grande do Sul.

• Particularidade de Payload: Comunicação via REST nativo da IPM, exigindo código NBS e consulta síncrona pós-emissão para extração do XML fiscal definitivo.

7. Demais Engines Homologadas em Produção:

• DBSeller: Porto Alegre/RS e dezenas de municípios gaúchos e paranaenses.
• Tinus: Cidades de Pernambuco, Rio de Janeiro e interior de Minas Gerais.
• SpeedGov: Cidades paulistas e mineiras sob o padrão SpeedGov.
• ISSNet: Goiânia/GO, Ribeirão Preto/SP, Campo Grande/MS e diversas capitais.
• DSF: Campinas/SP, Sorocaba/SP, Belém/PA, São Luís/MA, Teresina/PI.
• WebISS, Fiorilli, Centi, Coplan, Sigep, HM2, Salvador, Brasília DF e Pronim (famílias SNNFSE e ABRASF).

🔍 API Pública de Cobertura de Cidades (GET /api/v1/cobertura/cidades)

Para permitir que produtos digitais e times de desenvolvimento validem programaticamente se um cliente pode emitir notas antes mesmo de disparar a primeira transação, a Notaas disponibiliza um endpoint público de consulta:

GET https://platform.notaas.com.br/api/v1/cobertura/cidades?q={termo}&uf={uf}&ibge={ibge}&limit={limit}

Diferenciais de Engenharia do Endpoint:

• Público e Desacoplado: Não exige chave de autenticação para chamadas em portais de documentação, onboarding ou checkout.
• Latência Sub-150ms: Os 5.571 municípios estão compilados estaticamente em memória no processo Node.js (cidades-cobertura.generated.json). A consulta não gera concorrência no pool PostgreSQL de produção da API de emissão.
• Edge Cache Global: Responde com o header Cache-Control: public, max-age=86400, stale-while-revalidate=3600, permitindo cache imediato na rede global da Cloudflare.

Parâmetros Suportados:

• q (string, opcional): Nome do município (com ou sem acento, busca case-insensitive, mínimo de 2 caracteres).
• uf (string, opcional): Sigla da Unidade Federativa com 2 caracteres (ex: SP, MG, PR).
• ibge (string, opcional): Código IBGE de 7 dígitos para busca exata (ex: 3550308 para São Paulo).
• limit (number, opcional): Quantidade máxima de resultados retornados (padrão: 15, máximo: 50).

Exemplo de Requisição via cURL:

curl -s "https://platform.notaas.com.br/api/v1/cobertura/cidades?q=Cubatao&uf=SP" | jq .

Resposta JSON:

{
  "municipios": [
    {
      "codigo_ibge": "3513504",
      "nome_municipio": "Cubatão",
      "sigla_uf": "SP",
      "codigo_tom": "6369",
      "status": "ativo",
      "engine": "tbw",
      "familia_engine": "tbw",
      "tipo_cobertura": "Municipal Próprio",
      "snnfse_aderente": false
    }
  ],
  "total": 1
}

💻 Payloads Canônicos: Emitindo em Diferentes Engines sem Alterar o Backend

A força da arquitetura Notaas está em manter o contrato HTTP idêntico para a sua aplicação: você sempre envia para POST /api/v1/emitir. Apenas os campos específicos do serviço variam de acordo com as exigências da engine da cidade.

1. Exemplo: Emissão em São Paulo Capital (sp_prefeitura)

Preenchimento clássico com codigoServico municipal paulistano:

{
  "tipo": "nfse",
  "ambiente": "producao",
  "referencia": "PEDIDO-SP-9821",
  "prestador": {
    "cnpj": "12345678000195",
    "inscricaoMunicipal": "54321098"
  },
  "tomador": {
    "cpfCnpj": "98765432000109",
    "razaoSocial": "Empresa Contratante S/A",
    "email": "nfe@empresa.com.br",
    "endereco": {
      "logradouro": "Avenida Brigadeiro Faria Lima",
      "numero": "1485",
      "bairro": "Pinheiros",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "01452002"
    }
  },
  "servico": {
    "discriminacao": "Desenvolvimento e manutencao de software de automacao financeira sob demanda",
    "valorServicos": 8500.00,
    "codigoServico": "02800",
    "aliquota": 2.90,
    "issRetido": false
  }
}

2. Exemplo: Emissão em Cubatão / SP (Engine tbw com NBS Obrigatória)

Demonstrando o envio da NBS de 9 dígitos e do código de subitem LC 116:

{
  "tipo": "nfse",
  "ambiente": "producao",
  "referencia": "FAT-LOG-4491",
  "prestador": {
    "cnpj": "12345678000195",
    "inscricaoMunicipal": "19482"
  },
  "tomador": {
    "cpfCnpj": "11222333000144",
    "razaoSocial": "Terminal Logistico de Cargas LTDA",
    "endereco": {
      "logradouro": "Rodovia Conego Domenico Rangoni",
      "numero": "S/N",
      "bairro": "Polo Industrial",
      "codigoMunicipio": "3513504",
      "uf": "SP",
      "cep": "11500000"
    }
  },
  "servico": {
    "discriminacao": "Servicos de gerenciamento logistico de cargas alfandegadas e controle portuario",
    "valorServicos": 14200.00,
    "itemListaServico": "11.02",
    "nbs": "114011000",
    "aliquota": 5.00,
    "issRetido": false
  }
}

3. Exemplo: Emissão no Sistema Nacional da NFS-e (snnfse)

Emissão via padrão nacional da Receita Federal, com código de tributação nacional:

{
  "tipo": "nfse",
  "ambiente": "producao",
  "referencia": "ASSINATURA-SAAS-1029",
  "prestador": {
    "cnpj": "12345678000195"
  },
  "tomador": {
    "cpfCnpj": "44555666000177",
    "razaoSocial": "Comercio de Suprimentos Brasil LTDA",
    "endereco": {
      "logradouro": "Rua Central dos Andradas",
      "numero": "320",
      "bairro": "Centro",
      "codigoMunicipio": "3106200",
      "uf": "MG",
      "cep": "30130000"
    }
  },
  "servico": {
    "discriminacao": "Licenciamento de software como servico (SaaS) - Gestao operacional",
    "valorServicos": 1990.00,
    "codigoTributacaoNacional": "010701",
    "aliquota": 3.00,
    "issRetido": false
  }
}

💻 Integração Completa em TypeScript / Node.js com Validação Zod

Abaixo apresentamos um exemplo de arquitetura limpa em Node.js / TypeScript com verificação prévia de disponibilidade e envio resiliente:

import axios from 'axios';
import { z } from 'zod';

const NOTAAS_BASE_URL = 'https://platform.notaas.com.br/api/v1';
const NOTAAS_API_KEY = process.env.NOTAAS_API_KEY || 'sk_live_sua_chave';

// 1. Schema de validação do retorno de cobertura
const CoberturaResponseSchema = z.object({
  municipios: z.array(
    z.object({
      codigo_ibge: z.string(),
      nome_municipio: z.string(),
      sigla_uf: z.string(),
      status: z.enum(['ativo', 'engine_nao_implementada', 'sem_webservice']),
      engine: z.string(),
      snnfse_aderente: z.boolean(),
    })
  ),
  total: z.number(),
});

// 2. Função de checagem prévia de disponibilidade
export async function validarDisponibilidadeMunicipio(ibge: string): Promise<boolean> {
  try {
    const response = await axios.get(`${NOTAAS_BASE_URL}/cobertura/cidades?ibge=${ibge}`, {
      timeout: 5000,
    });
    
    const parsed = CoberturaResponseSchema.parse(response.data);
    if (parsed.total > 0 && parsed.municipios[0].status === 'ativo') {
      console.log(`[Notaas Cobertura] Cidade ${parsed.municipios[0].nome_municipio}/${parsed.municipios[0].sigla_uf} habilitada na engine ${parsed.municipios[0].engine}.`);
      return true;
    }
    
    console.warn(`[Notaas Cobertura] Cidade com IBGE ${ibge} ainda sem suporte automatizado.`);
    return false;
  } catch (err) {
    console.error('[Notaas Cobertura] Erro ao consultar endpoint de cobertura:', err);
    return false;
  }
}

// 3. Função de emissão assíncrona da nota fiscal de serviço
export async function dispararEmissaoNfse(payload: Record<string, unknown>) {
  const { data } = await axios.post(`${NOTAAS_BASE_URL}/emitir`, payload, {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': NOTAAS_API_KEY,
    },
    timeout: 12000,
  });

  return data;
}

🏢 Org API: Gestão Multi-Cliente para BPOs Contábeis e Software Houses

Para escritórios de contabilidade que realizam a gestão fiscal de múltiplos clientes PJ, ou para plataformas SaaS que operam como ERPs verticais (gestão para clínicas médicas, academias, escolas ou oficinas mecânicas), o cadastro manual de clientes é um gargalo operacional insustentável.

A Notaas oferece a Org API (POST /api/v1/org/projects), permitindo provisionar novos CNPJs 100% via código:

curl -X POST https://platform.notaas.com.br/api/v1/org/projects \
  -H "Authorization: Bearer org_admin_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clinica Medica Sao Lucas LTDA",
    "cnpj": "12345678000195",
    "inscricaoMunicipal": "987654",
    "cnaePrincipal": "8630503",
    "certificadoA1": {
      "base64": "MIIKmwIBAzCCCmYGCSqGSIb3DQEHAaCCC...",
      "senha": "senha_do_certificado"
    }
  }'

Vantagens da Arquitetura Multi-Tenant da Org API:

• Tokens Independentes: Cada projeto criado recebe sua própria apiKey, impossibilitando que dados de faturamento de uma empresa vazem para outra.
• Certificados Digitais Seguros: Armazenamento criptografado em repouso com envelopamento de chaves AES-256 e rotação auditável.
• Monitoramento Centralizado: O escritório contábil gerencia todos os CNPJs através de um único painel administrativo ou via webhooks globais.

Veja mais detalhes técnicos em nosso artigo exclusivo sobre como integrar múltiplos CNPJs em uma única API de NFS-e.

❓ Perguntas Frequentes sobre Cobertura de NFS-e (FAQ)

1. O que ocorre se uma prefeitura decidir mudar de software ou aderir ao Sistema Nacional?

Essa é uma das ocorrências mais frequentes e prejudiciais para quem faz integrações manuais diretas: a prefeitura publica um decreto mudando de fornecedor municipal e o webservice antigo é desligado do dia para a noite. Na Notaas, nós monitoramos ativamente os diários oficiais e o portal da Receita Federal. O chaveamento de rota ocorre na camada da API Notaas de maneira totalmente transparente, sem necessidade de você alterar uma única linha de código no seu sistema.

2. É necessário possuir um Certificado Digital para cada município emitido?

Não. O Certificado Digital A1 é de titularidade do CNPJ do emitente. Caso sua empresa ou cliente emita em filiais ou municípios distintos onde possua inscrição municipal ativa sob o mesmo CNPJ, o mesmo certificado digital A1 é reutilizado pela API.

3. Como a Reforma Tributária (IBS e CBS) impacta a emissão de NFS-e municipal?

A Emenda Constitucional nº 132/2023 unifica gradualmente o ISS municipal e o ICMS estadual no IBS (Imposto sobre Bens e Serviços) e na CBS (Contribuição sobre Bens e Serviços). O Sistema Nacional da NFS-e (SNNFSE) é o alicerce escolhido pela Receita Federal para a transição dos serviços. Na Notaas, os esquemas JSON já estão prontos para receber a tríade fiscal de NBS, Código de Classificação Tributária (cClassTrib) e alíquotas de IBS/CBS, eliminando rejeições como o erro E637. Aprofunde-se no nosso guia sobre IBS/CBS na NFS-e para contadores e software houses.

4. A Notaas cobra taxa de adesão ou mensalidade mínima por município?

Não. Na Notaas, a cobrança é unificada por volume de notas emitidas com sucesso, independentemente da cidade ser atendida por webservice municipal legado ou pelo Sistema Nacional. Além disso, disponibilizamos 50 notas fiscais gratuitas por mês por CNPJ em produção real, sem pegadinhas nem exigência de cartão de crédito.

🚀 Comece a Emitir em Escala Nacional com a Notaas

Chega de perder semanas desenvolvendo conectores para prefeituras instáveis. Foque no core business do seu produto e deixe a complexidade fiscal com a Notaas:

• 50 notas fiscais gratuitas por mês por CNPJ em produção real.
• 4.202 municípios já ativos e prontos para faturamento.
• Geração Local de DANFSe v2.0 (NT-008): PDFs rápidos e sem falhas de renderização.
• Documentação Interativa de Cobertura: Consulte sua cidade em tempo real no nosso Guia de Municípios da Notaas.

👉 Crie sua conta gratuita na Notaas Platform e faça sua primeira emissão de teste hoje mesmo.