Leiaute nacional da NT-009: contrato da API de NFS-e

Esta página detalha o contrato da API de NFS-e para o leiaute nacional da NT SE/CGNFS-e 009 v1.01 (Anexo VI v1.04.01, schema 1.02). Para a visão geral da norma, veja NT-009 da NFS-e nacional.

Por enquanto, só notas de homologação

Desde 26/10/2026, a DPS no leiaute da NT-009 é gerada somente nas notas de homologação (tpAmb = 2):

• Notas emitidas pelo Ambiente Nacional: automaticamente.
• Prefeituras com emissor próprio no padrão nacional: depois da ativação pela NFE.io, por prefeitura, quando a homologação da prefeitura aceitar o schema 1.02.

Nas notas de produção, a DPS continua no leiaute atual (1.01) e os campos novos são ignorados, com exceção dos quatro campos de intenção listados em Validações antes do envio.

Leiaute preliminar

O schema 1.02 usado pela NFE.io ainda não é a versão oficial (versão de 06/10/2026). Campos e regras desta página podem mudar quando a versão oficial for publicada. O Ambiente Nacional também ainda não processa todos os grupos: em 26/10/2026, a produção restrita recusava as notas de ajuste, os pagamentos vinculados, o comércio exterior e os condomínios.

Princípios do contrato

• Todos os campos novos são opcionais. Uma requisição que não os usa continua válida, em homologação e em produção.
• Nenhum valor novo em enum existente. ibsCbs.purpose, foreignTrade.serviceMode, deduction.documents[].deductionType e ibsCbs.thirdPartyReimbursements.documents[].reimbursementType mantêm os mesmos valores. O que é exclusivo da NT-009 entrou em campos novos.
• Nenhum campo foi removido ou renomeado. O serviceAmountInCurrency continua aceito, mas não é enviado no leiaute novo (o vServMoeda saiu do schema 1.02).

Campos novos da API

Campo (JSON)	Tipo	Tag XML	Regras
ibsCbs.adjustmentPurpose	string (enum)	finNFSe	Credit (1) ou Debit (2). Ausente = nota regular (0). Campo de intenção
ibsCbs.debitAdjustmentType	string (enum)	tpNFSeDebito	CooperativeCreditTransfer (01), CreditAnnulmentExemptOutflows (02), UnprocessedInvoiceDebits (03), FinesAndInterest (04), SuccessionCreditTransfer (05), AdvancePayment (06). Obrigatório com adjustmentPurpose = Debit
ibsCbs.creditAdjustmentType	string (enum)	tpNFSeCredito	FinesAndInterest (01), SuccessionCreditTransfer (05). Obrigatório com adjustmentPurpose = Credit
ibsCbs.adjustment	objeto { ibsAmount, cbsAmount }	gIBSCBS/gIBSCBSAjuste (vIBS, vCBS)	Valores a ajustar. Obrigatório nos ajustes sem serviço (débito 01, 02, 03 e 05; crédito 05). Nos demais, não é enviado
ibsCbs.simplesNacionalApuration	string (enum)	prest/regTrib/regApIBSCBSSN	IbsAndCbsBySimplesNacional (1), CbsBySimplesNacionalIbsRegular (2), IbsAndCbsRegular (3). Só para optante ou optante pendente do Simples Nacional
ibsCbs.simplesNacionalActivityCode	string	serv/cServ/cAtvSN	"07" a "14" ou "90". Só para optante ou optante pendente do Simples Nacional
ibsCbs.movableAssets[]	array (até 1000) de { ncmCode, ncmDescription, quantity }	IBSCBS/bensMoveis	NCM com 8 dígitos, descrição até 150 caracteres, quantidade de 1 a 999. Locação de bens móveis (código de tributação 99.04.01)
ibsCbs.condominium	objeto	IBSCBS/condominios	originalDueDate; charges[] (1 a 20: type 1 Ordinário, 2 Privativo, 3 FPP, 4 Impostos e taxas, 5 Fundo de reserva, 99 Outra; typeDescription; amount; details[] até 20, com type 1 a 36 ou 999, typeDescription e amount); discounts[] (até 10: type 1 incondicionado ou 2 condicionado, amount, description). Código de tributação 99.05.01
ibsCbs.paymentLinks[]	array (até 99)	IBSCBS/gPgtoVinc/pgto	number (1 a 999, opcional; padrão = posição), transactionId (2 a 35 caracteres, sem espaço), paymentMethod (15 Boleto, 17 Pix dinâmico, 18 TED, 20 Pix estático, 23 Pix automático, 24 TEF), receiverFederalTaxNumber (CNPJ), paymentInstitutionBaseTaxNumber (CNPJ completo do PSP, 14 posições)
ibsCbs.foreignTradeBaseCalculationAdjustment	número	valores/vAjusteBC/vAjusteBCIBSCBSComExt	Ajuste da base do IBS/CBS no comércio exterior. Com o prestador emitente, só na exportação
realEstate.municipalityCode	string (IBGE, 7 dígitos)	imovel/cMun	Obrigatório no grupo. 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. Código de tributação 99.03
realEstate.propertyUnits[]	array (até 99)	imovel/gUnidImob	propertyFiscalRegistration (até 30), cibCode (8), address (mesmo formato de siteAddress), baseCalculationAdjustments[] (até 10: type 1 Tributos inclusos, 2 Emolumento, 3 Condomínio, 4 Redutor social, 99 Outras; typeDescription, obrigatória para 99; amount). Informe propertyUnits ou o formato atual (cibCode/siteAddress), não os dois
foreignTrade.invoiceNumber	string (até 20)	comExt/nFatura	Número da fatura
foreignTrade.invoiceAmount	número	comExt/vFatura	Valor da fatura
foreignTrade.exchangeContractNumber	string (até 20)	comExt/nContCambio	Número do contrato de câmbio
foreignTrade.concurrentConsumption	booleano	comExt/mdPrestacao = 5	Consumo concomitante no Brasil e no exterior. true vence o serviceMode. Campo de intenção
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. Campo de intenção
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. Campo de intenção

Exemplos

Os valores são fictícios.

Simples Nacional:

{
  "ibsCbs": {
    "simplesNacionalApuration": "IbsAndCbsBySimplesNacional",
    "simplesNacionalActivityCode": "07"
  }
}

NFS-e de ajuste de débito sem serviço:

{
  "ibsCbs": {
    "classCode": "000001",
    "adjustmentPurpose": "Debit",
    "debitAdjustmentType": "CooperativeCreditTransfer",
    "adjustment": { "ibsAmount": 120.50, "cbsAmount": 45.30 }
  }
}

Pagamento vinculado:

{
  "ibsCbs": {
    "paymentLinks": [
      {
        "transactionId": "E12345678202610261200abcdef1234",
        "paymentMethod": 17,
        "receiverFederalTaxNumber": "11222333000181",
        "paymentInstitutionBaseTaxNumber": "00000000000191"
      }
    ]
  }
}

O que muda no XML da DPS (leiaute novo)

• finNFSe, indDest e dest: a finalidade e o destinatário passam a ser obrigatórios em toda DPS. finNFSe vem de ibsCbs.adjustmentPurpose (ausente = 0, Credit = 1, Debit = 2).
• CST e cClassTrib em trib: o CST e a classificação tributária do IBS/CBS passam a ir no grupo trib.
• vAjusteBC substitui vDedRed e gReeRepRes:
  • Os documentos de dedução do ISSQN (deduction.documents) viram docAjusteBC, com tpAjusteBC igual ao código do deductionType (tipos 2, 5, 6, 7, 8 e 99) ou ao baseCalculationAdjustmentType. O documento é identificado só por nfseKey, nfeKey ou nonFiscalDocumentNumber.
  • O tipo 1 (FoodAndBeverages, alimentação e bebidas) foi descontinuado pela NT-009: a nota é recusada antes do envio.
  • Os reembolsos de terceiros (ibsCbs.thirdPartyReimbursements) viram docAjusteBC, com tipos 101 a 104 e 199, derivados do reimbursementType, ou o baseCalculationAdjustmentType.
• Grupo imovel: cMun (obrigatório no grupo), gLocacao e gUnidImob. Sem realEstate.propertyUnits, os campos atuais (propertyFiscalRegistration, cibCode, siteAddress) viram uma única unidade.
• Grupos bensMoveis, condominios e gPgtoVinc: a partir de movableAssets, condominium e paymentLinks.
• Simples Nacional: passa a existir o opSimpNac = 4 (optante pendente), além de regApIBSCBSSN e cAtvSN. O opSimpNac = 4 vem do regime SimplesNacionalOptantePendente no cadastro da empresa.
• cServ: a ordem passa a ser cTribNac, cTribMun, cNBS, cAtvSN, cIntContrib e xDescServ, por último.
• Grupo comExt: nDI vira nDUIMP (15 caracteres alfanuméricos), nRE vira nDUE (14 caracteres alfanuméricos), entram nFatura, vFatura e nContCambio, e o vServMoeda deixa de ser enviado.
• atvEvento/cMun: nos subitens 12.13 e 17.10, quando o município do evento é diferente do local da prestação.
• CST 400, 410 e 820: gIBSCBS e cIndOp são omitidos.
• Notas de ajuste sem serviço (débito 01, 02, 03 e 05; crédito 05): levam o gIBSCBSAjuste e não levam regEspTrib, valores/trib, cIndOp, tpOper, gRefNFSe, tpEnteGov nem imovel. Exigem ibsCbs.classCode com CST que leve o grupo IBS/CBS (não 400, 410 ou 820).
• Documentos de vAjusteBC: o fornecedor (fornec) leva endereço, telefone e e-mail quando informados. As descrições são cortadas em 150 caracteres.

Validações antes do envio

Quando a validação recusa a nota, ela termina como falha de emissão, com o motivo na mensagem, e o webhook é disparado. Nenhuma chamada é feita ao governo.

Nota no leiaute atual (inclusive toda nota de produção)

A nota é recusada quando informa um dos campos de intenção, que só existem na NT-009:

• ibsCbs.adjustmentPurpose;
• foreignTrade.concurrentConsumption = true;
• baseCalculationAdjustmentType em qualquer documento de dedução ou de reembolso.

Os demais campos novos são ignorados.

Nota no leiaute novo (homologação)

Grupo	Motivo da recusa
Nota de ajuste	adjustmentPurpose sem o tipo correspondente (debitAdjustmentType ou creditAdjustmentType); ajuste sem serviço sem adjustment.ibsAmount e adjustment.cbsAmount; ajuste sem serviço sem classCode ou com CST 400, 410 ou 820
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 identificado
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 ou sem typeDescription; 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 do PSP é o CNPJ completo, não a raiz de 8 posições)

Webhook

Os campos novos aparecem no payload do webhook somente quando você os enviou. Eles nunca são preenchidos pela plataforma, e campos nulos não são serializados. Uma nota sem dados da NT-009 gera o mesmo payload de antes.

Veja também

• NT-009 da NFS-e nacional
• NFS-e de ajuste de IBS/CBS
• Ambiente na emissão de NFS-e