NT009 da NFS-e Nacional – Alterações no leiaute, IBS/CBS e regras de emissão (atualizado pela versão 1.01)

A Nota Técnica 009, versão 1.01, atualiza o leiaute da NFS-e Nacional para contemplar novas situações de emissão, adequações relacionadas à Reforma Tributária e alterações nas regras de validação.

Entre os principais temas estão o CNPJ alfanumérico, as notas de ajuste de débito e crédito de IBS/CBS, as operações com bens imóveis e bens móveis, o Simples Nacional, o comércio exterior e as operações de condomínios.

A versão 1.01 também corrige definições da versão anterior e atualiza a estrutura de determinados campos e grupos do XML.

Nos dois produtos, a NT009 é opcional e ativada por nota: versaoEsquema: "RTC009" no PlugNotas e Versao=RTC009 no TX2. Sem essa marcação, a emissão continua como antes.

1. O que muda com a NT009

1.1 Impacto no PlugNotas (API REST)

No PlugNotas, a NT009 é aplicada por nota, de forma opcional, pelo campo:

versaoEsquema: "RTC009"

Sem esse campo, o XML do leiaute anterior é mantido e os campos exclusivos da NT009 são descartados, sem erro, exceto: modoPrestacao = 5 é recusado; endereço no exterior exige logradouro, numero e bairro, e o cep do exterior aceita de 1 a 11 caracteres (erro 400 fora disso); a razaoSocial do intermediário passa a ir no XML (xNome). A RTC009 inclui as regras da RTC007 (retenção e apuração própria de PIS/COFINS/CSLL), então não é preciso informar as duas.

O que a API faz sozinha (com RTC009):

• grava CST e cClassTrib em valores/trib, antes de gIBSCBS;
• leva finNFSe, tpNFSeDebito e tpNFSeCredito (finalidade) para a raiz de infDPS; indDest e dest (destinatário) ficam dentro de IBSCBS enquanto a Release 2 da Sefin (item 2.11) não é aceita pelo ambiente nacional;
• põe xDescServ no fim de serv/cServ (depois de cIntContrib) e cAtvSN entre cNBS e cIntContrib, na ordem do XSD oficial;
• envia o ajuste de base de cálculo com o nome corrigido vAjusteAplic;
• devolve, na consulta da nota autorizada, a versão da calculadora (versaoCalculadoraIBSCBS), quando a Sefin informa.

O que o integrador precisa informar (quando se aplica à operação): os campos novos em servico[].ibscbs (ajusteBC, valorAjusteBCIBSCBSComExt, imovel.locacao e imovel.unidadesImoveis, bensMoveis, pagamentosVinculados, tpNFSeDebito/tpNFSeCredito, valores.ajusteIBSCBS), em servico[].infExterior (numeroFatura, valorFatura, numeroDUIMP, numeroDUE, numeroContratoCambio e modoPrestacao = 5), servico[].evento.codigoCidade, servico[].codigoAtividadeSN e, no cadastro da empresa, regimeApuracaoIBSCBSSN. Com RTC009 o codigoOperacao (cIndOp) passa a ser opcional; a Sefin valida a consistência com o CST.

⚠️ Ainda não aceitos pelo ambiente nacional: hoje a produção restrita da Sefin só aceita a Release 1 da NT009. Estes campos continuam documentados, mas a API retorna erro 400 se forem informados com RTC009: item 2.2 (sem data de implantação definida pela Sefin) — finalidadeNFSe diferente de 0, tpNFSeDebito, tpNFSeCredito e valores.ajusteIBSCBS; item 2.4 (sem data) — regimeApuracaoIBSCBSSN e codigoAtividadeSN; item 2.8 (sem data) — pagamentosVinculados; item 2.12 (Release 2) — numeroFatura, valorFatura, numeroDUIMP, numeroDUE, numeroContratoCambio e modoPrestacao = 5; item 2.13 (Release 2) — valorAjusteBCIBSCBSComExt; item 2.14 (Release 2) — servico[].evento.codigoCidade. No item 2.12, enquanto ele estiver bloqueado, numeroDeclaracaoImp e numeroRegistroExp (nDI/nRE) continuam aceitos e enviados. O valorServicos (vServMoeda) do comércio exterior é obrigatório. Até a liberação, a API/o componente retorna erro se o campo for informado. A liberação é feita por item e por ambiente, conforme a Sefin (homologação primeiro, produção depois): liberar um item não libera os outros.

Sem RTC009 × Com RTC009

Exemplo – PlugNotas (CST 400, sem codigoOperacao e sem gIBSCBS)

{
  "versaoEsquema": "RTC009",
  "servico": [
    {
      "ibscbs": {
        "finalidadeNFSe": 0,
        "operacaoPessoal": 0,
        "destinatario": { "indicador": 0 },
        "valores": {
          "tributacao": {
            "cst": "400",
            "cct": "400001"
          }
        }
      }
    }
  ]
}

Atenção: o cronograma da NT009 é o divulgado pela Sefin Nacional (produção em 03/11/2026) e pode mudar. Em homologação (produção restrita), a Sefin já só autoriza notas com RTC009: o XSD oficial publicado em 20/10/2026 exige o finNFSe na raiz de infDPS, e a nota sem RTC009 é rejeitada. Em produção, o leiaute anterior continua aceito até a Sefin mudar. O XSD oficial traz só a Release 1; os itens da Release 2 serão liberados quando a Sefin publicar o XSD correspondente. Teste em homologação com RTC009 antes de usar em produção.

1.1.1 Guia técnico completo

Para exemplos detalhados com cenários práticos, tabela de decisão e FAQ completo, consulte o guia técnico interativo:

📄 Abrir: Guia Técnico NT009 - IBS/CBS e leiaute

O guia inclui:

• Explicação detalhada de cada campo da API, com o campo gerado no XML
• Tabela de decisão "quando informar o quê" (locação, CST sem gIBSCBS, comércio exterior, evento 17.10, Simples Nacional, notas de ajuste)
• 5 cenários práticos lado a lado (JSON da API ↔ XML gerado), incluindo a comparação com a nota legada
• Orientações de migração do formato anterior e do modelo RTC007
• FAQ com respostas para dúvidas mais comuns

1.1.2 Teste no Sandbox e exemplos da documentação da API

O ambiente Sandbox do PlugNotas (https://api.sandbox.plugnotas.com.br) já está atualizado com os novos campos da NT009. Você pode testar o seu JSON antes da produção: envie a nota com versaoEsquema: "RTC009" e os campos novos que se aplicam à operação.

O Sandbox valida o JSON e as regras da RTC009 da mesma forma que a produção e devolve os mesmos erros de validação. A nota autorizada que ele retorna é simulada: a DPS não é enviada à Sefin Nacional e não tem validade fiscal.

A documentação da API no Postman traz exemplos prontos de requisição da NT009. Abra nfse Nacional → Emitir nota nacional de serviço e escolha o exemplo em Example Request:

• NOTA RTC009: nota básica com a RTC009;
• NOTA RTC009 IMÓVEL (LOCAÇÃO): locação 99.03 com copropriedade e unidades imobiliárias;
• NOTA RTC009 COMÉRCIO EXTERIOR: modo de prestação 5, DU-E, fatura, contrato de câmbio e ajuste da base de cálculo do IBS/CBS;
• NOTA RTC009 AJUSTE DE BC (DF-e): ajusteBC com documento fiscal;
• NOTA RTC009 AJUSTE BC ISSQN: valorAjusteBCISSQN, que substitui valor.deducoes;
• NOTA RTC009 PAGAMENTOS VINCULADOS: pagamento via PIX.

⚠️ Os exemplos NOTA RTC009 COMÉRCIO EXTERIOR (itens 2.12 e 2.13) e NOTA RTC009 PAGAMENTOS VINCULADOS (item 2.8) usam campos que o ambiente nacional ainda não aceita: hoje o Sandbox, como a produção, devolve erro 400 para eles. Eles passam a autorizar quando a Sefin liberar esses itens.

📄 Abrir: Documentação da API PlugNotas (Postman)

1.2 Impacto no Componente NFSe (TX2)

No Componente, a NT009 é ativada no cabeçalho do TX2 com Versao=RTC009. Sem essa linha o componente gera o XML como antes. O preenchimento é manual: o componente não calcula nada automaticamente.

Campos TX2 novos (os nomes são os mesmos da API do PlugNotas):

• Comércio exterior: NumeroFatura, ValorFatura, NumeroDUIMP, NumeroDUE, NumeroContratoCambio, CodigoModoPrestacao (valor 5), ValorAjusteBCIBSCBSComExt — ⚠️ ainda não aceitos pelo ambiente nacional (NT009 itens 2.12 e 2.13, Release 2 da Sefin): até a liberação o componente retorna erro se forem informados
• Evento: CodigoCidadeEvento — ⚠️ ainda não aceito pelo ambiente nacional (NT009 item 2.14, Release 2 da Sefin): até a liberação o componente retorna erro se for informado
• Notas de ajuste: TipoNFSeDebito, TipoNFSeCredito, ValorIBSAjuste, ValorCBSAjuste (e FinalidadeNFSe diferente de 0) — ⚠️ ainda não aceitos pelo ambiente nacional (NT009 item 2.2, sem data de implantação definida pela Sefin): até a liberação o componente retorna erro se forem informados
• Ajuste de BC: PercentualAjusteBCISSQN, ValorAjusteBCISSQN e o bloco DOCAJUSTEBC (TipoAjusteBC, DescricaoAjusteBC, ValorTotalDocumento, ValorAjusteAplicado, DataEmissaoDocAjuste, DataCompetenciaDocAjuste, TipoChaveDFeAjuste, ChaveDFeAjuste, entre outros)
• Imóvel/locação: CodigoMunicipioImovel, PercentualCopropriedade, ValorTotalOperacaoImovel, ValorDescontoIncondTotalImovel, ValorDescontoCondicTotalImovel, DataVencimentoOriginalImovel e os blocos UNIDADEIMOBILIARIA (InscricaoFiscalImovelUnidade, CodigoCIBUnidade…) e AJUSTEBCIMOV (TipoAjusteBCLocImoveisUnidade, DescricaoAjusteBCLocImoveisUnid, ValorAjusteBCLocImoveisUnidade)
• Bens móveis e pagamentos vinculados: NCMBemMovel, DescricaoBemMovel, QuantidadeBemMovel; NumeroPagamento, IdentificadorTransacao, TipoMeioPagamento, CNPJRecebedor, CNPJBasePSP — os pagamentos vinculados ⚠️ ainda não são aceitos pelo ambiente nacional (NT009 item 2.8, sem data de implantação definida pela Sefin): até a liberação o componente retorna erro se forem informados
• Simples Nacional: RegimeApuracaoIBSCBSSN, CodigoAtividadeSN e OptanteSimplesNacional = 4 — ⚠️ ainda não aceitos pelo ambiente nacional (NT009 item 2.4, sem data de implantação definida pela Sefin): até a liberação o componente retorna erro se forem informados

Com Versao=RTC009 o componente também grava CST/cClassTrib e a finalidade nas novas posições do XML (o destinatário, indDest/dest, fica dentro de IBSCBS por enquanto), e xDescServ no fim de serv/cServ. Para usar a RTC009 é preciso rodar o AtualizarArquivos: ele traz os scripts, esquemas e o nfseLocaisNacional.ini da NT009, e é por ele que chega a liberação de cada item, que segue a da Sefin por ambiente. Quem não atualizar fica sem a NT009 e, quando a Sefin mudar a posição do indDest/dest (item 2.11), terá as notas RTC009 rejeitadas. Os campos NumeroDeclaracaoImp e NumeroRegistroExp (nDI/nRE) continuam aceitos, enquanto NumeroDUIMP e NumeroDUE retornam erro até a liberação do item 2.12.

Exemplo – TX2 (trecho, locação 99.03)

formato=tx2
padrao=TecnoNFSeNacional
Versao=RTC009

INCLUIRDPS
...
ValorServicos=500.00
CodigoItemListaServico=990301
FinalidadeNFSe=0
OperacaoPessoal=1
CodigoOperacao=020201
IndicadorDestinatario=0
CodigoMunicipioImovel=4115200
PercentualCopropriedade=50.00
ValorTotalOperacaoImovel=1000.00
SituacaoTributariaIbsCbs=200
ClassificacaoTributariaIbsCbs=200027
SALVARDPS
INCLUIRUNIDADEIMOBILIARIA
InscricaoFiscalImovelUnidade=12345678901234567890
CodigoCIBUnidade=12345678
INCLUIRAJUSTEBCIMOV
TipoAjusteBCLocImoveisUnidade=01
ValorAjusteBCLocImoveisUnidade=25.50
SALVARAJUSTEBCIMOV
SALVARUNIDADEIMOBILIARIA

2. Erros comuns após a NT009

• Esquecer versaoEsquema: "RTC009" (ou Versao=RTC009 no TX2) e esperar os campos novos no XML.
• Enviar campos da NT009 sem a RTC009: eles são descartados (e modoPrestacao = 5 é recusado).
• Informar codigoOperacao com CST que não tem o grupo gIBSCBS (como 400, 410 e 820).
• Locação (99.03) sem o grupo locacao, sem codigoOperacao 02XXXX ou com valor do serviço que não é copropriedade × valor total da operação.
• Enviar inscricaoFiscal, codigoCIB ou endereco na raiz de imovel com a RTC009: a API rejeita a nota. Use codigoMunicipio, locacao e unidadesImoveis.
• Informar codigoCIB e endereco juntos na mesma unidade imobiliária: são alternativos e, com a RTC009, a API devolve erro de validação.
• No Componente, informar com Versao=RTC009 os campos e blocos que a NT009 substituiu: ValorDeducoes e ValorPercDeducoes diferentes de zero, os blocos DEDUCAO e DOCUMENTOREFERENCIADO ou os campos do imóvel na raiz (InscricaoFiscalImovel, CodigoCIB, CepImovel e demais). O componente rejeita o TX2, como a API, e a mensagem indica o substituto: o bloco DOCAJUSTEBC, PercentualAjusteBCISSQN ou ValorAjusteBCISSQN no lugar da dedução e dos documentos referenciados, e CodigoMunicipioImovel com o bloco UNIDADEIMOBILIARIA no lugar do imóvel.
• Informar numeroDUIMP/numeroDUE (nDUIMP/nDUE), numeroFatura, valorFatura, numeroContratoCambio ou modoPrestacao = 5 (NumeroDUIMP, NumeroDUE, NumeroFatura, ValorFatura, NumeroContratoCambio e CodigoModoPrestacao=5 no TX2) com a RTC009: o item 2.12 da NT009 ainda não é aceito pelo ambiente nacional (Release 2 da Sefin) e a API e o componente retornam erro. Enquanto isso, numeroDeclaracaoImp/numeroRegistroExp (nDI/nRE) continuam aceitos e enviados. Quando o item 2.12 for liberado, a situação se inverte: nDI/nRE passam a ser rejeitados e valem numeroDUIMP/numeroDUE (são documentos diferentes, sem conversão automática).
• Informar com a RTC009 qualquer outro campo ainda não aceito pelo ambiente nacional: finalidadeNFSe diferente de 0, tpNFSeDebito, tpNFSeCredito, valores.ajusteIBSCBS (item 2.2), regimeApuracaoIBSCBSSN, codigoAtividadeSN (item 2.4), pagamentosVinculados (item 2.8), valorAjusteBCIBSCBSComExt (item 2.13) e servico[].evento.codigoCidade (item 2.14). A API devolve erro 400 e o componente rejeita o TX2, com a mensagem "... ainda não é aceito pelo ambiente nacional". Remova o campo; ele será liberado quando a Sefin aceitar.
• Enviar deducao, documentosReferenciados, valor.deducoes ou valor.percentualDeducoes com a RTC009: a API rejeita a nota, porque os grupos vDedRed e gReeRepRes foram unificados em vAjusteBC. Informe ajusteBC, valorAjusteBCISSQN e percentualAjusteBCISSQN. Não há conversão automática, porque os tipos mudaram.
• Usar tipoAjuste 1, 3 ou 4 em ajusteBC: esses tipos existiam no antigo vDedRed e foram descontinuados pelo item 2.3 da NT009. A API rejeita; use 2, 5 a 9, 99, 101 a 105 ou 199.
• Não respeitar a regra de nDI/nRE (hoje) ou de DUIMP/DU-E (depois da liberação do item 2.12): com tipoMovimentacaoBens = 2 o numeroDeclaracaoImp é obrigatório (erro E0352); com 3, o numeroRegistroExp é obrigatório (E0356); com 1, nenhum dos dois pode ser informado (E0354). Vale para a API do PlugNotas com a RTC009: enquanto o item 2.12 não é aceito (padrão), as três regras valem sobre numeroDeclaracaoImp/numeroRegistroExp e numeroDUIMP/numeroDUE retornam erro; depois da liberação, passam a valer sobre numeroDUIMP/numeroDUE. A mensagem de erro cita o código da regra. O componente não aplica essas três regras: a Sefin as valida.
• Não informar indicador do destinatário (indDest) nem finalidadeNFSe (finNFSe) com a RTC009: o XSD oficial exige os dois e, sem eles, o ambiente nacional rejeita a nota. A API e o componente não preenchem esses campos sozinhos. Informe destinatario.indicador (0 quando o destinatário é o próprio tomador) e finalidadeNFSe (hoje só 0 é aceito; no TX2, IndicadorDestinatario e FinalidadeNFSe).
• Informar descricaoAjuste em ajustesBCLocImoveis (DescricaoAjusteBCLocImoveisUnid no TX2) com tipoAjuste diferente de 99: a descrição só é aceita com o tipo 99 (erro E0954, vale sempre com a RTC009). A API devolve 400 e o componente rejeita o TX2.
• Tomador, intermediário ou fornecedor do ajuste de base de cálculo com endereço no exterior sem logradouro, numero ou bairro (o XSD exige os três mesmo com endereço do exterior), ou com cep de mais de 11 caracteres: a API devolve 400, com e sem RTC009. O código postal do exterior aceita de 1 a 11 caracteres (por exemplo 10115) e é enviado como veio, no tomador, no intermediário, no destinatário e no fornecedor do ajuste de base de cálculo; o CEP nacional continua com 8 dígitos. A razão social do intermediário (razaoSocial) vai no XML (xNome) quando informada: é opcional na API, mas o leiaute de produção atual exige o xNome no intermediário, então informe-a. O estado do destinatário e do fornecedor do ajuste é a sigla de 2 letras no endereço nacional e, no exterior, texto livre de 1 a 60 caracteres (por exemplo Berlin). codigoPais diferente de BR/1058, ou codigoCidade = 9999999, indica endereço no exterior; o XML leva só os campos do exterior (endExt), sem código de município nem CEP nacionais. No componente, use CodigoCidade<Grupo>=9999999 (prestador, tomador, intermediário, fornecedor) e, no destinatário, PaisDestinatario diferente de 1058 ou CodigoCidadeDestinatario=9999999 (campos PaisDestinatario, CodigoPostalDestinatario, DescricaoCidadeDestinatario e UfDestinatario).
• Omitir o grupo evento no subitem 17.10. O município do evento (codigoCidade) ainda não é aceito pelo ambiente nacional (item 2.14, Release 2 da Sefin); depois da liberação ele só pode ser informado nos subitens 12.13 e 17.10.

3. Conclusão

A NT009 v1.01 amplia o leiaute da NFSe Nacional para a Reforma Tributária do Consumo. No PlugNotas a adoção é opcional e por nota: com versaoEsquema: "RTC009" a API cuida do novo leiaute do XML e você informa apenas os campos novos que se aplicam à operação.

Todos os integradores devem acompanhar o cronograma oficial da Sefin e testar em homologação antes da produção. Para quem utiliza o PlugNotas, a RTC009 também mantém as regras da NT007, sem exigir configuração adicional.

Documentação oficial

A NT009 v. 1.01 deve ser consultada em conjunto com os anexos técnicos aplicáveis, que detalham o leiaute, as regras de negócio e os indicadores de operação.

Consulte a documentação oficial:

Nota Técnica 009 – Versão 1.01 (PDF)

Portal Nacional da NFS-e – Documentação Técnica

Notícia: Ato Técnico Conjunto RFB/CGIBS nº 7 aprova a versão 1.01 da NT009

Observação técnica: em 20/10/2026 a Sefin publicou o XSD oficial da produção restrita, só com a Release 1 da NT009. Para os itens da Release 2 e os ainda sem data, o Anexo VI v1.04.01 é a referência de leiaute e regras de negócio, e esses itens ficam bloqueados até a Sefin aceitá-los. Consulte as publicações oficiais mais recentes antes de utilizar a estrutura como referência definitiva de integração.