NFS-e: leiaute nacional da NT 009
Para quem é este comunicado: clientes que emitem NFS-e via integração, especialmente prestadores optantes pelo Simples Nacional e quem emite nota de ajuste de IBS/CBS, locação, condomínio, pagamento vinculado ou serviço com comércio exterior.
O que muda no seu lado: nada, até a NFE.io ativar o leiaute da NT 009 na prefeitura que você usa. A mudança é aditiva e opcional. A requisição que você envia hoje continua válida.
Visão geral
A NT SE/CGNFS-e 009 v1.01 reestrutura a DPS do padrão nacional da NFS-e. A API de NFS-e da NFE.io já aceita os campos novos desse leiaute. A mudança é aditiva e opcional: ela só passa a valer na prefeitura que for ativada para o leiaute NT 009, e nada muda para quem não a ativa.
A NT SE/CGNFS-e 009 v1.01, o Anexo VI v1.04.01 e o Anexo VII v1.03.00 reestruturam a DPS do padrão nacional da NFS-e. A API de NFS-e da NFE.io já aceita todos os campos desse leiaute.
O que isso significa para a sua integração:
- Nenhum campo foi removido ou renomeado na API. Todos os campos novos são opcionais e nuláveis. Uma requisição que você envia hoje continua válida.
- A mudança é ativada por prefeitura, pela NFE.io, e vem desligada. Enquanto a prefeitura não estiver no leiaute NT 009, o XML gerado continua o de hoje e os campos novos são ignorados.
- Quatro campos são exclusivos do leiaute NT 009. Se você enviar um deles para uma prefeitura que ainda não está no leiaute, a nota é recusada antes do envio, com mensagem, e o webhook é disparado. A lista está na seção "Validações que recusam a nota antes do envio".
- A emissão pelo Ambiente Nacional segue configuração própria. MEI e as notas roteadas para a Sefin Nacional não seguem a opção da cidade.
- A NT ainda não traz cronograma de produção. Por isso disponibilizamos o leiaute em homologação, para que você se prepare com antecedência.
O que recomendamos fazer agora: revisar os campos das seções seguintes, identificar quais se aplicam ao seu negócio e solicitar a ativação em homologação.
O schema usado no desenvolvimento (XSD v1.02) não é a versão oficial nem a mais recente, e a NT 009 não tem cronograma de produção. Campos, cardinalidades e regras desta página podem mudar quando a versão oficial for publicada. Vamos atualizar a documentação e comunicar as diferenças quando isso acontecer. A lista dos pontos em que há maior chance de ajuste está em "Ressalvas importantes".
O que mudou
O que muda, por tema
| Tema | O que a NT 009 traz | Campos da API envolvidos |
|---|---|---|
| Simples Nacional | Passam a ser informados o regime de apuração do IBS/CBS do optante e o código da atividade. Surge o optante pendente (opSimpNac = 4). | ibsCbs.simplesNacionalApuration, ibsCbs.simplesNacionalActivityCode |
| NFS-e de ajuste | A NFS-e passa a ter finalidade de ajuste de crédito ou de débito, com tipo e valores de IBS/CBS a ajustar. | ibsCbs.adjustmentPurpose, ibsCbs.debitAdjustmentType, ibsCbs.creditAdjustmentType, ibsCbs.adjustment |
| Deduções e reembolsos | Deduções do ISSQN e reembolsos de terceiros passam a sair como ajuste da base de cálculo, com código próprio por documento. | deduction.documents[].baseCalculationAdjustmentType, ibsCbs.thirdPartyReimbursements.documents[].baseCalculationAdjustmentType |
| Bens imóveis | O grupo de imóvel ganha município, dados de locação e lista de unidades imobiliárias, cada uma com endereço e parcelas fora da base de cálculo. | realEstate.municipalityCode, realEstate.leasing, realEstate.propertyUnits[] |
| Bens móveis | Locação de bens móveis passa a listar os bens por NCM. | ibsCbs.movableAssets[] |
| Condomínios | Operações condominiais passam a detalhar cobranças, detalhamentos e descontos. | ibsCbs.condominium |
| Pagamentos vinculados | A NFS-e passa a poder referenciar as transações de pagamento que a liquidam. | ibsCbs.paymentLinks[] |
| Comércio exterior | Entram fatura, contrato de câmbio, consumo concomitante e o ajuste da base de cálculo na exportação. | foreignTrade.invoiceNumber, foreignTrade.invoiceAmount, foreignTrade.exchangeContractNumber, foreignTrade.concurrentConsumption, ibsCbs.foreignTradeBaseCalculationAdjustment |
As seções seguintes detalham cada campo, o que foi alterado e o que foi descontinuado.
Simples Nacional: prazo da obrigatoriedade
O Ato Conjunto RFB/CGIBS nº 4/2026 (art. 1º, § 1º) fixa em 01/01/2027 o início da obrigatoriedade de emissão dos documentos com IBS/CBS para os contribuintes optantes pelo Simples Nacional. Até 31/12/2026, a omissão do IBS/CBS na NFS-e não acarreta a rejeição do documento pelo sistema nacional, segundo a orientação publicada pela SE/CGNFS-e em 07/08/2026. A falta evidencia a desconformidade do documento fiscal, sujeitando o emitente às sanções e aos prazos do Ato Conjunto.
Novos campos da API
Todos os campos abaixo são opcionais e nuláveis. Nenhum campo existente foi removido ou renomeado na API.
| Campo (JSON) | Tipo | Tag XML | Observação |
|---|---|---|---|
ibsCbs.adjustmentPurpose | string | finNFSe | Credit (1) ou Debit (2); ausente = nota regular (0). Exclusivo do leiaute NT 009. |
ibsCbs.debitAdjustmentType | string | tpNFSeDebito | CooperativeCreditTransfer (01), CreditAnnulmentExemptOutflows (02), UnprocessedInvoiceDebits (03), FinesAndInterest (04), SuccessionCreditTransfer (05), AdvancePayment (06). Obrigatório com adjustmentPurpose = Debit. |
ibsCbs.creditAdjustmentType | string | tpNFSeCredito | FinesAndInterest (01), SuccessionCreditTransfer (05). Obrigatório com adjustmentPurpose = Credit. |
ibsCbs.adjustment | objeto { ibsAmount, cbsAmount } | gIBSCBS/gIBSCBSAjuste | Valores a ajustar. Obrigatório nos ajustes sem tributo (débito 01, 02, 03 e 05; crédito 05). |
ibsCbs.simplesNacionalApuration | string | prest/regTrib/regApIBSCBSSN | IbsAndCbsBySimplesNacional (1), CbsBySimplesNacionalIbsRegular (2), IbsAndCbsRegular (3). Só para optante ou optante pendente do Simples. |
ibsCbs.simplesNacionalActivityCode | string | serv/cServ/cAtvSN | "07" a "14" ou "90". |
ibsCbs.movableAssets[] | array (até 1000) | IBSCBS/bensMoveis | ncmCode (8 dígitos), ncmDescription (até 150), quantity (1 a 999). cTribNac 99.04.01. |
ibsCbs.condominium | objeto | IBSCBS/condominios | originalDueDate, charges[] (1 a 20), discounts[] (até 10). cTribNac 99.05.01. |
ibsCbs.paymentLinks[] | array (até 99) | IBSCBS/gPgtoVinc/pgto | number, transactionId, paymentMethod, receiverFederalTaxNumber, paymentInstitutionBaseTaxNumber. |
ibsCbs.foreignTradeBaseCalculationAdjustment | número | valores/vAjusteBC/vAjusteBCIBSCBSComExt | Com o prestador emitente, só em exportação. |
realEstate.municipalityCode | string (IBGE, 7) | imovel/cMun | Se ausente, usa siteAddress.city.code, depois o município da unidade ou o local da prestação. |
realEstate.leasing | objeto | imovel/gLocacao | coOwnershipPercentage (0 a 100, padrão 100), totalOperationAmount, unconditionalDiscountTotal, conditionalDiscountTotal, originalDueDate. cTribNac 99.03. |
realEstate.propertyUnits[] | array (até 99) | imovel/gUnidImob | propertyFiscalRegistration, cibCode, address, baseCalculationAdjustments[]. |
foreignTrade.invoiceNumber | string (até 20) | comExt/nFatura | |
foreignTrade.invoiceAmount | número | comExt/vFatura | |
foreignTrade.exchangeContractNumber | string (até 20) | comExt/nContCambio | |
foreignTrade.concurrentConsumption | booleano | comExt/mdPrestacao = 5 | true vence o serviceMode. Exclusivo do leiaute NT 009. |
deduction.documents[].baseCalculationAdjustmentType | inteiro | docAjusteBC/tpAjusteBC | 2, 5, 6, 7, 8, 9 ou 99; vence o código derivado do deductionType. Use 9 para profissional parceiro. Exclusivo do leiaute NT 009. |
ibsCbs.thirdPartyReimbursements.documents[].baseCalculationAdjustmentType | inteiro | docAjusteBC/tpAjusteBC | 101 a 105 ou 199; vence o código derivado do reimbursementType. Use 105 para glosa de serviços de saúde. Exclusivo do leiaute NT 009. |
Exemplos de payload
Os valores abaixo são fictícios e servem só para ilustrar o formato.
Simples Nacional: regime de apuração do IBS/CBS e código da atividade:
{
"ibsCbs": {
"simplesNacionalApuration": "IbsAndCbsBySimplesNacional",
"simplesNacionalActivityCode": "07"
}
}
NFS-e de ajuste de débito, sem tributo: exige o tipo e os valores a ajustar:
{
"ibsCbs": {
"adjustmentPurpose": "Debit",
"debitAdjustmentType": "CooperativeCreditTransfer",
"adjustment": { "ibsAmount": 120.50, "cbsAmount": 45.30 }
}
}
Imóvel com unidades imobiliárias: o formato novo, uma entrada por unidade:
{
"realEstate": {
"municipalityCode": "3550308",
"leasing": {
"coOwnershipPercentage": 100,
"totalOperationAmount": 5000.00,
"originalDueDate": "2026-11-10"
},
"propertyUnits": [
{
"propertyFiscalRegistration": "1234567890",
"cibCode": "12345678",
"address": {
"postalCode": "01310100",
"street": "Avenida Paulista",
"number": "1000",
"district": "Bela Vista"
},
"baseCalculationAdjustments": [
{ "type": 3, "amount": 350.00 }
]
}
]
}
}
Bens móveis e pagamentos vinculados:
{
"ibsCbs": {
"movableAssets": [
{ "ncmCode": "84295211", "ncmDescription": "Escavadeira hidráulica sobre esteiras", "quantity": 2 }
],
"paymentLinks": [
{
"transactionId": "E00000000202610151200abcdef01",
"paymentMethod": 17,
"receiverFederalTaxNumber": "11222333000181",
"paymentInstitutionBaseTaxNumber": "11222333000181"
}
]
}
}
Condomínio: cobranças, detalhamento e descontos:
{
"ibsCbs": {
"condominium": {
"originalDueDate": "2026-11-10",
"charges": [
{
"type": 1,
"typeDescription": "Taxa condominial ordinária",
"amount": 850.00,
"details": [
{ "type": 999, "typeDescription": "Limpeza e conservação", "amount": 300.00 }
]
}
],
"discounts": [
{ "type": 2, "amount": 50.00, "description": "Pagamento até o vencimento" }
]
}
}
}
Comércio exterior: fatura, câmbio, consumo concomitante e ajuste da base:
{
"foreignTrade": {
"invoiceNumber": "FAT-2026-0098",
"invoiceAmount": 12500.00,
"exchangeContractNumber": "CC-884512",
"concurrentConsumption": true
},
"ibsCbs": {
"foreignTradeBaseCalculationAdjustment": 1200.00
}
}
Documento de dedução: baseCalculationAdjustmentType vence o código derivado do deductionType:
{
"deduction": {
"documents": [
{
"nfseKey": "00000000000000000000000000000000000000000000000001",
"deductionType": "Subcontracting",
"baseCalculationAdjustmentType": 9,
"issueDate": "2026-10-01",
"deductibleTotal": 2000.00,
"usedAmount": 1500.00
}
]
}
}
Campos alterados, descontinuados e removidos
Na API, nada foi removido nem renomeado. As mudanças abaixo acontecem no XML gerado (DPS) quando a prefeitura está no leiaute NT 009. Os campos da API continuam sendo aceitos como hoje.
| Campo da API | O que acontece no leiaute NT 009 |
|---|---|
foreignTrade.serviceAmountInCurrency | Continua aceito na API, mas não é mais enviado no XML: vServMoeda foi removido do XSD v1.02. |
foreignTrade.importDeclaration (nDI) | Passa a ser enviado como nDUIMP, com 15 caracteres alfanuméricos, sem truncar o valor. |
foreignTrade.exportRegistration (nRE) | Passa a ser enviado como nDUE, com 14 caracteres alfanuméricos. |
foreignTrade.serviceMode | Continua valendo, mas concurrentConsumption = true vence o valor informado e envia mdPrestacao = 5. |
deduction.documents[].deductionType = "FoodAndBeverages" (tipo 1) | Descontinuado pela NT 009. A nota é recusada antes do envio, com mensagem. |
deduction.documents[].municipalNfse e fiscalDocumentNumber | Não identificam o documento no leiaute NT 009. Use nfseKey, nfeKey ou nonFiscalDocumentNumber. |
realEstate.propertyFiscalRegistration, cibCode, siteAddress | Continuam aceitos: viram uma única unidade imobiliária (gUnidImob). Informe este formato ou propertyUnits, não os dois. |
purpose | Continua com o único valor regular. As NFS-e de ajuste são informadas em adjustmentPurpose, não aqui. |
Nenhum enum existente ganhou valor novo. ibsCbs.purpose, foreignTrade.serviceMode, deduction.documents[].deductionType e thirdPartyReimbursements.documents[].reimbursementType seguem com os mesmos valores de hoje. O que é exclusivo da NT 009 entrou em campos novos, justamente para não mudar o comportamento de quem não usa o leiaute.
Outras mudanças no XML gerado:
finNFSe,indDestedestsaem do grupoIBSCBSe passam para a raiz deinfDPS.CSTecClassTribpassam a ser informados no grupotrib.vAjusteBCsubstituivDedRedegReeRepRes.cServé reordenado, comxDescServpor último.atvEvento/cMunpassa a ser enviado nos subitens 12.13 e 17.10, quando o município do evento difere do local da prestação.- Nos CST 400, 410 e 820,
gIBSCBSecIndOpsão omitidos. - Nos ajustes sem tributo, a DPS também não leva
regEspTrib,valores/trib,cIndOp,tpOper,gRefNFSe,tpEnteGovnemIBSCBS/imovel.
Validações que recusam a nota antes do envio
A validação roda no início do processamento da nota, para qualquer provedor. Quando ela recusa, a nota termina como falha de emissão, com o motivo na mensagem, e o webhook é disparado, sem nenhuma chamada à prefeitura.
Prefeitura fora do leiaute NT 009. A nota é recusada quando informa um destes quatro campos:
ibsCbs.adjustmentPurposeforeignTrade.concurrentConsumption = truededuction.documents[].baseCalculationAdjustmentTypeibsCbs.thirdPartyReimbursements.documents[].baseCalculationAdjustmentType
Os demais campos novos são simplesmente ignorados nessa prefeitura.
Prefeitura no leiaute NT 009:
| Grupo | Motivo da recusa |
|---|---|
| Nota de ajuste | adjustmentPurpose sem o tipo correspondente (debitAdjustmentType ou creditAdjustmentType); ajuste sem tributo (débito 01, 02, 03 e 05; crédito 05) sem adjustment.ibsAmount e adjustment.cbsAmount. |
| Documento de dedução | Sem tipo, issueDate, deductibleTotal ou usedAmount; tipo 1 (descontinuado) ou fora de 2, 5, 6, 7, 8, 9 e 99; tipo 99 sem otherDeductionDescription; identificado só por NFS-e municipal ou documento fiscal avulso. |
| Documento de reembolso | Tipo fora de 101 a 105 e 199; sem amount, issueDate ou documento; tipos 101, 103, 104 e 199 sem documento fiscal (otherNationalDfe ou otherFiscalDoc); otherFiscalDoc com accrualOn a partir de 2026. |
| Imóvel | Unidade sem cibCode nem CEP; leasing sem totalOperationAmount; município do imóvel não resolvido. |
| Bens móveis | NCM sem 8 dígitos, sem descrição ou quantidade fora de 1 a 999. |
| Condomínio | Sem originalDueDate ou sem cobrança; cobrança ou detalhe sem tipo; tipo 99 ou 999 sem descrição; desconto com tipo fora de 1 e 2 ou sem descrição. |
| Pagamentos vinculados | transactionId fora de 2 a 35 caracteres ou com espaço; paymentMethod fora de 15, 17, 18, 20, 23 e 24; CNPJ do recebedor ou do PSP ausente ou inválido. |
O campo paymentInstitutionBaseTaxNumber exige o CNPJ completo, com 14 posições, e não a raiz de 8. Essa regra mudou com a versão do XSD de 06/10/2026.
Como o campo é tratado, conforme a prefeitura. Os quatro campos exclusivos são ibsCbs.adjustmentPurpose, foreignTrade.concurrentConsumption = true e os dois baseCalculationAdjustmentType (dedução e reembolso). Qualquer outro campo novo enviado a uma prefeitura fora do leiaute é apenas ignorado: a nota é emitida normalmente.
Ativação e testes em homologação
A troca de leiaute é feita pela NFE.io, no cadastro da prefeitura. Não há nada a enviar na requisição para escolher o leiaute. O padrão é o leiaute atual.
Para testar sem mexer na sua produção, existe uma configuração separada, que vale somente nas emissões de homologação (as notas fora do ambiente de produção). Com ela ligada, as notas de homologação daquela prefeitura saem no leiaute NT 009 e as de produção continuam no leiaute atual. Uma nota de produção nunca usa essa configuração.
Como se preparar:
- Identifique, na seção "O que muda, por tema", quais cenários se aplicam ao seu negócio.
- Solicite a ativação do leiaute NT 009 em homologação para as prefeituras que você usa.
- Emita em homologação com os campos novos e confira o XML gerado e o payload do webhook.
- Mantenha a produção como está até que o cronograma oficial seja publicado.
Emissão pelo Ambiente Nacional. A nota emitida pelo Ambiente Nacional (MEI e as notas roteadas para a Sefin Nacional) não segue a configuração da cidade. Ela segue uma configuração própria do Ambiente Nacional. Colocar um provedor municipal no leiaute NT 009 não muda a emissão pela Sefin Nacional. Quando a nota é recusada, a mensagem indica qual dos dois destinos está no leiaute antigo.
O que não muda
- Sua integração atual. Uma requisição que não usa os campos novos continua válida e gera o mesmo XML de hoje, nos dois leiautes.
- Os endereços e a autenticação da API. Nenhuma rota nova, nenhuma versão nova.
- Os valores dos enums existentes. Nada foi acrescentado a
ibsCbs.purpose,foreignTrade.serviceMode,deductionTypeoureimbursementType. - O payload do webhook, para quem não usa os campos novos. Eles só aparecem no payload quando você os enviou na requisição: são opcionais, nunca preenchidos pela plataforma, e campos nulos não são serializados. Uma nota sem dados da NT 009 gera exatamente o mesmo payload de antes.
Ressalvas importantes
O leiaute é preliminar e pode sofrer pequenas alterações. A NT SE/CGNFS-e 009 v1.01 e o Anexo VI v1.04.01 já foram publicados, mas o schema (XSD v1.02) usado no desenvolvimento não é a versão oficial e não é a última versão disponível. Campos, cardinalidades e regras desta documentação podem mudar quando a versão oficial for publicada. Vamos atualizar a documentação e comunicar as diferenças quando isso acontecer.
Alguns pontos já conhecidos em que a NT e o Anexo divergem do XSD preliminar, e onde, portanto, há maior chance de ajuste:
- Obrigatoriedade de
docAjusteBC/dtEmiDoce degUnidImob/end/xBairro. - Cardinalidade dos campos de condomínio (
xTpCobranca,vCobranca,xTpDetCobranca,vDetCobranca,vDesconto). - Sinal de
vAjusteBCIBSCBSComExt(a NT admite valor negativo; o XSD preliminar, não). - Tipo de
nFaturaenContCambio(numérico na NT, texto no XSD). - Precisão de
pCopropriedade.
Sujeito a alterações legais pelo Governo. A NT 009 ainda não traz cronograma de entrada em produção.
Próximos passos
- 📩 Compartilhe este comunicado com quem mantém a sua integração de NFS-e.
- 🔎 Identifique quais temas se aplicam ao seu negócio e revise os campos correspondentes.
- 🧪 Solicite a ativação do leiaute NT 009 em homologação para as prefeituras que você usa.
- 🏭 Mantenha a produção como está até que o cronograma oficial seja publicado.
- 💬 Dúvidas sobre este comunicado ou pedido de ativação em homologação: fale com o seu contato na NFE.io ou abra um chamado pelo suporte.
Documentação
| Página | Para que serve |
|---|---|
| NT-009 da NFS-e nacional: ajustes de IBS/CBS | O que a NT 009 estabelece e como afeta a sua emissão. |
| Documentação do layout de emissão de NFS-e (RTC) | Referência completa de cada campo, com as regras de validação. A seção com os campos da NT 009 entra no ar junto com a liberação em homologação. |
| Mudanças no layout de integração da NFS-e | Comparação entre o layout anterior e o atual, campo a campo. |
| NFS-e de ajuste de IBS/CBS (crédito e débito) | Situação atual da nota de ajuste. |
| Referência completa de campos de emissão de NFS-e | Contrato do payload de emissão. |
| Tabelas de referência da Reforma Tributária | Indicador de operação (indOp), CST e classificação tributária, correlação LC 116 x NBS, comércio exterior. |
| Monitoramento da adesão dos municípios ao Ambiente Nacional | Em que situação está cada município. |
| Perguntas e respostas sobre a Reforma Tributária | Dúvidas frequentes. |
| Release notes | Histórico de mudanças da plataforma. |
FAQ
Preciso alterar a minha integração agora? Não. Nenhum campo foi removido ou renomeado, e uma requisição que não usa os campos novos continua gerando o mesmo XML de hoje. A mudança só vale na prefeitura que a NFE.io ativar para o leiaute NT 009.
Quando a NT 009 entra em produção? Ainda não há cronograma. A NT 009 não traz data de produção. A NFE.io disponibiliza o leiaute em homologação, sob solicitação, para você se preparar.
O que acontece se eu enviar um campo novo para uma prefeitura que ainda não está no leiaute NT 009?
Quase todos os campos novos são ignorados e a nota é emitida normalmente. Quatro campos são exclusivos do leiaute (ibsCbs.adjustmentPurpose, foreignTrade.concurrentConsumption = true e os dois baseCalculationAdjustmentType): com eles, a nota é recusada antes do envio, com mensagem, e o webhook é disparado.
Sou optante do Simples Nacional. Quando preciso destacar IBS e CBS? Pelo Ato Conjunto RFB/CGIBS nº 4/2026, a obrigatoriedade de emissão dos documentos com IBS/CBS para optantes do Simples Nacional começa em 01/01/2027. Até 31/12/2026, a omissão não é rejeitada pelo sistema nacional, mas evidencia a desconformidade do documento.
O schema da NFE.io é o oficial? Não. O schema usado no desenvolvimento (XSD v1.02) não é a versão oficial nem a mais recente. Quando a versão oficial for publicada, atualizamos a documentação e comunicamos as diferenças.
Em resumo:
- A API já aceita os campos da NT 009. Todos opcionais e nuláveis. Nada foi removido ou renomeado.
- A mudança é ativada por prefeitura, em homologação, sob solicitação. Sem ativação, o XML continua o de hoje. Quatro campos exclusivos recusam a nota em prefeitura fora do leiaute.
- Sem cronograma de produção e com leiaute preliminar. O XSD usado não é o oficial e pode haver ajustes.
- Simples Nacional: regime de apuração do IBS/CBS, código da atividade e optante pendente entram no leiaute. A obrigatoriedade de emissão com IBS/CBS para optantes começa em 01/01/2027.