Documentação Técnica - Padrão NFS-e Nacional

Esta documentação existe para explicar as regras e os recursos do padrão NFS-e Nacional (SNNFSe) que seguimos na emissão integrada via PlugNotas e Componente NFS-e Nacional. Aqui você encontra: ambientes/portais, autenticação, métodos disponíveis (emissão, consulta, eventos, substituição), observações de negócio e um conjunto de erros comuns e referências oficiais.Consulte este manual principalmente se você é:

• Cliente/integrador (dev/tech lead): para entender ambientes, autenticação por certificado, fluxo (DPS → NFS-e), métodos e pontos de atenção.

Tópicos deste artigo (Sumário)

• Manual do web service

• PortaPortais disponíveisis disponíveis

• Métodos disponíveis

• Tipo de impressão

• Observações gerais do padrão

• Observações específicas por município

• Emissão pelo PlugNotas

• Emissão pelo Componente NFS-e Nacional

• Observações sobre a geração do XML/DPS

• Erros comuns

• Campos customizados para impressão

• Compatibilidade / versões mínimas

Manual do web service

• Manual do Contribuinte – Emissor Público API (v1.2 / out-2025): descreve serviços de NFS-e, DPS e Eventos (métodos e comportamento, incluindo substituição).

• Página oficial de APIs (Produção Restrita e Produção): lista Swaggers por módulo (CNC, ADN, Parametrização, DANFSe e Sefin).

• Manual portal municipal (conceitual/processo): detalha o processo DPS → validação → recepção da NFS-e.

Portais disponíveis

Métodos disponíveis

Emissão

• Envio sequencial (RPS em sequência): (X) Necessita ( ) Não necessita
  Nota: “envio sequencial” = a numeração do RPS precisa seguir a sequência esperada pelo web service.

• Modo: (X) Síncrono ( ) Assíncrono ( ) Ambos

• Lote de RPS: (X) Aceita lote ( ) Não aceita lote

Consulta

• ( ) Consulta de lote

• (X) Consulta por RPS

• () Consulta por NFS-e

• ( ) Consulta por protocolo

• (X) Consulta notas tomadas

Cancelamento / Eventos

• (X) Cancelamento de NFS-e via web service

• ( ) Cancelamento apenas administrativo (fora do web service)

Substituição

• Oficial: ao enviar uma DPS contendo chave de acesso de uma NFS-e existente para substituir, o sistema gera Evento de Cancelamento por Substituição, cancela a original e retorna a NFS-e substituta.

• Atenção: as restrições de substituição são frequentes e aparecem em rejeições específicas (ver seção “Erros comuns”).

Tipo de impressão

• (X) Impressão via link da prefeitura
  Os produtos fazem download do PDF gerado pela prefeitura.

• (X) Impressão via layout Tecnospeed
  Os produtos geram o PDF, aproximando ao máximo o layout da prefeitura.

Importante: o tipo de impressão depende do que o padrão permite. Não é possível editar livremente o layout além das opções suportadas pelo produto/padrão.

Observações gerais do padrão

• O tempo de processamento de uma nota pode variar de acordo com a disponibilidade do WEBSERVICE da PREFEITURA.
• Se o seu cliente nunca emitiu por WEBSERVICE, é bem provável que terá de passar por um processo de homologação/liberação junto a PREFEITURA.
• O tamanho máximo para um único envio (lote), é de 500 notas.

Observações específicas por município

Mesmo no padrão nacional, podem existir diferenças por município via convênio e parametrização (ex.: retenção, regras para substituição, eventos específicos, etc.). Use a tabela abaixo para registrar divergências reais quando identificadas:

Emissão pelo PlugNotas

Conteúdo voltado para quem usa PlugNotas.

Documentação completa do produto: docs.plugnotas.com.br

Visão geral (rotas principais)

• Emitir: POST /https://api.plugnotas.com.br/nfse

• Consultar (por ID ou protocolo): GET https://api.plugnotas.com.br/nfse/%7BidNotaOrProtocol%7D

• Baixar PDF: GET https://api.plugnotas.com.br/nfse/pdf/{idNota}  (somente CONCLUIDO ou CANCELADO)

• Baixar XML: GET https://api.plugnotas.com.br/nfse/xml/{idNota}

Pontos de atenção (para não travar em produção)

• Sandbox ≠ ambiente oficial: use Sandbox para validar fluxo/integração e só depois avance para Produção.

• Ative o parâmetro do produto nfseNacional no cadastro da empresa para transmissão ao ambiente nacional. 

Desta forma, os próximos envios serão realizados para os endpoints da NFS-e Nacional (em homologação ou produção). A ativação deste campo será possível apenas para as empresas com Regime tributário MEI, ou para empresa com outros regimes somente em municípios conveniados e com emissão ativas para a NFS-e Nacional de acordo com a listagem presente no portal oficial da Nota Fiscal Eletrônica.

Emissão pelo Componente NFS-e Nacional

Pré-requisitos

• Certificado digital do emitente + CNPJ com Inscrição Municipal (conforme exigência operacional do padrão).

• Token TecnoAccount para habilitar uso do componente via ConfigurarSoftwareHouse.

Configuração (conceito)

• Carregar configurações (LoadConfig) e configurar software house (ConfigurarSoftwareHouse).

• Definir ambiente do componente (produção/homologação) e, se necessário, parâmetros extras/forma de envio. 

Métodos principais

• Enviar(Tx2) — emite DPS/NFS-e a partir do TX2 (retorno por RetornoWS). 

  • Para saber mais sobre como preencher os campos do arquivo de integração, acesso nosso dicionário de dados do TX2 padrão unificado.

• ConsultarNFSe(chaveAcesso) / ConsultarEventosNFSe / ConsultarEventoNFSe

• CancelarNFSe(chaveAcesso)

• Distribuição: ConsultarDistribuicaoDFe(...) + TratarRetornoConsultaDFe(...)

Retorno do envio (como ler)

O retorno do Enviar traz cenários como:

• SUCESSO: nota autorizada, com dados como número, código de verificação, situação, XML etc.

• ERRO: motivo de rejeição (ex.: lote já enviado).

Arquivos de exemplo

• TX2 (padrão nacional):TX2ExemploNFSeNacional.tx2

• JSON: JSONExemploNacional.Json

• XML NFS-e: 

Erros comuns

• Para acessar nossa lista completa de rejeições, acesse: https://atendimento.tecnospeed.com.br/hc/pt-br/sections/36128806726935-Rejei%C3%A7%C3%B5es-NFS-e-Padr%C3%A3o-Nacional

Campos customizados para impressão

Impressão da NFS-E

BaseCalculo=String[15]
EnderecoPrestador=String[-]
EnderecoTomador=String[-]
OutrasInformacoes=String[255]
NfseSubstituida=String[10]
DataCancelamento=String[10]
RazaoSocialIntermediario=String[80]

Impressão do RPS

ValorIss=String[10]
OutrasRetencoes=String[10]
BaseCalculo=/RPS/ValorServicos
CnpjPrestador=String[14]
NomeFantasiaPrestador=String[80]
RazaoSocialPrestador=String[80]
EnderecoPrestador=String[80]
UfPrestador=String[2]
NumeroEnderecoPrestador=String[10]
ComplementoEnderecoPrestador=String[40]
BairroPrestador=String[40]
CepPrestador=String[8]
EnderecoTomador=/RPS/EnderecoTomador/Logradouro
OutrasInformacoes=String[255]
RazaoSocialIntermediario=String[80]
CodigoMunicipioPrestador=String[10]
DiscriminacaoServico=String[2000]
 

Compatibilidade / versões mínimas

• Componente NFS-e Nacional:

• PlugNotas: