API

Substituição de NFS-e no Padrão Nacional (SNNFSE): Grupo <subst>, chSubstda e Fluxo via API

Guia técnico completo sobre substituição de NFS-e no Sistema Nacional (SNNFSE / ADN): preenchimento do grupo <subst>, chave chSubstda de 50 dígitos, códigos cMotivo, cancelamento automático da nota anterior e diferenças para o cancelamento simples.

Fábio Magalhães CostaAtualizado em 22/11/2026
Fluxo de substituição de NFS-e no Padrão Nacional (SNNFSE) com grupo subst e chave de 50 dígitos via API

Fluxo de substituição de NFS-e no Padrão Nacional (SNNFSE) com grupo subst e chave de 50 dígitos via API

Diferente da NF-e de produtos (que possui Carta de Correção Eletrônica para pequenos ajustes), na Nota Fiscal de Serviços Eletrônica (NFS-e) do Padrão Nacional (SNNFSE / ADN) você não "edita" uma nota já autorizada. Quando o tomador avisa que o valor, a discriminação do serviço, a alíquota de ISS ou um dado cadastral saiu errado, existem apenas dois caminhos oficiais: cancelar a nota ou emitir uma NFS-e Substituta usando o grupo <subst> dentro da DPS.

Na prática em produção, muitos ERPs e sistemas de faturamento recorrente acabam fazendo "cancelar + emitir nova" de forma manual e desconectada — perdendo o vínculo fiscal entre os dois documentos e, em alguns municípios, gerando cobrança duplicada de ISS na virada de competência. Entender como o grupo <subst> funciona no Padrão Nacional da NFS-e resolve isso de forma atômica.


Substituição vs Cancelamento Simples: Quando usar cada um?

Critério Cancelamento Simples (e101101) Substituição de NFS-e (<subst> na DPS)
Quando usar O serviço não foi prestado ou a venda foi estornada/desistida. O serviço foi prestado, mas houve erro no valor, tomador, descrição, tributação ou retenções.
O que acontece no SNNFSE Registra o evento e101101 cancelando a NFS-e original; nenhuma nova nota é criada. Autoriza a nova NFS-e e dispara automaticamente o evento e105102 (Cancelamento por Substituição) na NFS-e anterior.
Vínculo fiscal no DANFSe v2.0 Nota original aparece apenas como Cancelada. A nova nota carrega a referência explícita da nota substituída (chSubstda) e a antiga aponta para a substituta.
Risco operacional Se o dev cancelar a nota antiga e a nova falhar por erro de schema, o cliente fica sem nota. Operação atômica: se a nova DPS for rejeitada por qualquer erro, a nota antiga permanece intacta e válida.

A grande vantagem de engenharia da substituição no SNNFSE é a atomicidade: você nunca corre o risco de cancelar uma nota válida e depois descobrir que a nota corrigida foi rejeitada pela prefeitura.


Anatomia do grupo <subst> dentro da <infDPS>

No schema oficial da DPS v1.01 (DPS_v1.01.xsd), o grupo <subst> é posicionado logo após os dados de identificação da DPS (antes de <prest>) e contém 3 tags:

⚡ Estrutura do Grupo <subst> no Padrão Nacional:

  • <chSubstda> (Obrigatória — 50 dígitos): Chave de acesso completa de 50 dígitos da NFS-e Nacional original que está sendo substituída (apenas números, sem o prefixo "NFS").
  • <cMotivo> (Obrigatória — 2 dígitos): Código padronizado do motivo da substituição na tabela do SNNFSE:
    • 01 — Desenquadramento de NFS-e do Simples Nacional
    • 02 — Enquadramento de NFS-e no Simples Nacional
    • 03 — Inclusão Retroativa de Imunidade/Isenção para NFS-e
    • 04 — Exclusão Retroativa de Imunidade/Isenção para NFS-e
    • 05 — Rejeição de NFS-e pelo tomador ou pelo intermediário se responsável pelo recolhimento do tributo
    • 99 — Outros (exige preenchimento de <xMotivo>)
  • <xMotivo> (Condicional — 15 a 255 caracteres): Descrição textual clara do motivo da substituição. Obrigatória sempre que cMotivo = 99 (e recomendada em todos os casos para auditoria contábil).

4 regras de validação do SNNFSE que mais causam rejeição na substituição

  1. A chave chSubstda tem 50 dígitos (não 44!): Diferente da NF-e/CT-e (44 dígitos), a chave da NFS-e Nacional tem 50 dígitos numéricos. Enviar o id com o prefixo NFS (53 caracteres) ou enviar o número da NFS-e em vez da chave gera rejeição imediata de schema.
  2. A nota original não pode já estar cancelada ou substituída: Tentar substituir uma nota que já sofreu e101101 ou e105102 retorna rejeição do Sefin Nacional.
  3. Mesmo CNPJ/CPF prestador: A DPS substituta precisa pertencer ao mesmo prestador da nota substituída, com um novo número de DPS (nDPS) (nunca reaproveite o nDPS da nota original).
  4. Prazo municipal de substituição: Mesmo no Padrão Nacional, cada município conveniado parametriza no CNC/SNNFSE o prazo limite em dias após a emissão (ou fechamento da competência do ISS) em que a substituição é permitida sem processo administrativo.

Como emitir uma NFS-e Substituta via API da Notaas

Na Notaas, você envia o objeto substituicao diretamente no payload JSON de POST /api/v1/emitir — e o mesmo contrato funciona tanto para prestadores com certificado .pfx próprio quanto para emissões no snnfse por Procuração Eletrônica RFB 00233 (org_proxy / wedigi_proxy).

{
  "tipo": "nfse",
  "ambiente": "homologacao",
  "externalId": "nfse_subst_fatura_2026_1102",
  "substituicao": {
    "chaveSubstituida": "35503082203167121000110000000000001226114829103847",
    "codigoMotivo": "99",
    "motivo": "Correcao do valor do servico e da discriminacao conforme contrato aditivo 04/2026"
  },
  "prestador": {
    "cnpj": "03167121000110"
  },
  "tomador": {
    "cpfCnpj": "11222333000181",
    "razaoSocial": "Empresa Tomadora Exemplo Ltda",
    "email": "financeiro@tomadora.com.br",
    "endereco": {
      "logradouro": "Av. Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "01310100"
    }
  },
  "servico": {
    "codigo": "01.05",
    "codigoTributacaoMunicipio": "010501",
    "descricao": "Licenciamento de uso de software SaaS - Competencia Novembro/2026 (Valor corrigido)",
    "valor": 1850.00,
    "aliquota": 2.00
  }
}

Assim que o Sefin Nacional autoriza a substituta:

  • A Notaas dispara o webhook assinado (HMAC-SHA256) com a nova chave de 50 dígitos, o XML atualizado e o DANFSe v2.0 (NT-008) renderizado localmente em < 180ms — já exibindo a referência da nota substituída.
  • Se você quiser inspecionar visualmente qualquer XML de NFS-e Nacional (original ou substituída) sem depender do portal do governo, basta arrastar o arquivo no nosso playground gratuito danfse.notaas.com.br.

E os campos de IBS e CBS na substituição?

Ao substituir uma NFS-e em 2026, a nova DPS passa por todas as regras atuais da Nota Técnica 009 (NT-009 / Anexo VIII — cIndOp, NBS e cClassTrib). Na Notaas, se você já salvou os defaults de IBS/CBS no perfil do CNPJ via Org API (PATCH /api/v1/org/projects/{id}), a nota substituta herda automaticamente a classificação tributária correta sem risco de Erro E637 ou E363.


Teste a substituição de NFS-e Nacional na prática

Crie sua conta gratuita na Notaas e teste emissões, cancelamentos e substituições de NFS-e em 4.836 cidades ativas — com 20 notas fiscais gratuitas por mês em produção real (1 CNPJ) + até 5 CNPJs em homologação via Org API, sem cartão de crédito.

Notaas — Infraestrutura Fiscal Multi-Tenant para SaaS, ERPs e BPOs

Escale a emissão de NFS-e, NF-e, NFC-e, CT-e e MDF-e para dezenas de CNPJs

Integre a API de Nota Fiscal da Notaas no seu software: provisione clientes via Org API Multi-CNPJ, isole certificados A1 em nuvem, receba webhooks assinados com HMAC e gere DANFSe v2.0 local. Sandbox ilimitado e planos sob medida para operações em escala.

Artigos Relacionados em API

Guias Pilares de Integração Fiscal