--- title: "Leiaute nacional da NT-009: contrato da API de NFS-e (homologação)" description: "Campos novos da API de NFS-e para o leiaute nacional da NT-009 v1.01 (schema 1.02), o que muda no XML da DPS, as validações antes do envio e o webhook. Por enquanto, o leiaute vale só para notas de homologação; em produção, nada muda." source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/contrato-leiaute-nt-009/ product: documentacao last_updated: 2026-10-26 tags: ["nfse", "reforma-tributaria", "nt-009", "ibs", "cbs", "homologacao", "contrato"] --- # 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](/legislacao/nt-009-nfse-nacional/). :::warning 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](#validações-antes-do-envio). ::: :::caution 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:** ```json { "ibsCbs": { "simplesNacionalApuration": "IbsAndCbsBySimplesNacional", "simplesNacionalActivityCode": "07" } } ``` **NFS-e de ajuste de débito sem serviço:** ```json { "ibsCbs": { "classCode": "000001", "adjustmentPurpose": "Debit", "debitAdjustmentType": "CooperativeCreditTransfer", "adjustment": { "ibsAmount": 120.50, "cbsAmount": 45.30 } } } ``` **Pagamento vinculado:** ```json { "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](/legislacao/nt-009-nfse-nacional/) - [NFS-e de ajuste de IBS/CBS](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/nfse-de-ajuste-ibs-cbs) - [Ambiente na emissão de NFS-e](/documentacao/nota-fiscal-servico-eletronica/duvidas/ambiente-na-emissao-nfse)