--- title: "Mudanças Funcionais no Layout de Integração da Nota Fiscal de Serviço (v4)" description: "Recomendamos revisar cuidadosamente a documentação de cada campo no novo JSON Schema e os exemplos fornecidos para garantir uma transição tranquila." source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4 last_updated: 2026-06-25 --- # Mudanças Funcionais no Layout de Integração da Nota Fiscal de Serviço (antigo vs. novo) :::warning Recomendamos revisar cuidadosamente a documentação de cada campo no novo JSON Schema e os exemplos fornecidos para garantir uma transição tranquila. ::: :::info * Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas. * Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria) ::: ## Objetivo Este documento detalha todas as mudanças funcionais introduzidas na versão "novo" do layout de integração da nota fiscal de serviço. A atualização incorpora primariamente os novos campos exigidos pela Reforma Tributária (IBS/CBS), mas também adiciona outros campos para melhorar a completude dos dados e alinhar-se aos novos padrões nacionais. ## Público-Alvo Desenvolvedores e usuários já familiarizados com o layout de integração anterior (antigo). ## Visão Geral das Mudanças Para alinhamento com a nova legislação tributária e os padrões nacionais, diversos campos e grupos foram adicionados. Embora a maioria dos campos existentes permaneça inalterada, a inclusão de novos campos obrigatórios é crucial para a emissão de notas no modelo novo. As principais mudanças são a adição dos grupos `ibsCbs` e `serviceAmountDetails`. No entanto, outros campos individuais e grupos opcionais mais complexos também foram introduzidos. ## 1. Grupo Principal: ibsCbs (Reforma Tributária) Este é o principal grupo adicionado ao layout e é **obrigatório**. Ele centraliza todas as informações relacionadas aos novos tributos, IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços), que substituirão o ICMS, ISS, PIS e COFINS. O objetivo deste grupo é fornecer ao fisco todos os detalhes necessários para o cálculo, apuração e fiscalização dos novos impostos, permitindo a correta distribuição da arrecadação entre os níveis federal, estadual e municipal. :::note ISSQN x IBS/CBS Os campos `taxationType` e `immunityType` na raiz da requisição referem-se **exclusivamente ao ISSQN** (período de transição). A tributação do **IBS e da CBS** é governada apenas pelos campos do grupo `ibsCbs` — principalmente `operationIndicator` e `classCode`. As regras de imunidade/redução dos novos tributos são expressas via `classCode` (ex.: códigos iniciados em `41xxxx`), e não pelo `immunityType`. ::: **Campos-chave dentro do grupo `ibsCbs`:** Dentro do grupo, os únicos campos **obrigatórios** são `operationIndicator` e `classCode`. - `operationIndicator` (string, **obrigatório**): Um código que especifica o tipo de operação de fornecimento, de acordo com uma nova tabela definida pelo fisco. - `classCode` (string, **obrigatório**): O Código de Classificação Tributária para o IBS/CBS, que determina as alíquotas e regimes aplicáveis. É uma **string** (ex.: `"000001"`), não um número. - `situationCode` (string, opcional): Código de Situação Tributária (CST) do IBS/CBS. Se não informado, é derivado automaticamente dos 3 primeiros dígitos do `classCode`. - `personalUse` (booleano, opcional): Indica se o serviço é para uso ou consumo pessoal. Relevante para a aplicação de regras tributárias específicas. - `destinationIndicator` (string, opcional): Indica o destinatário do serviço. Quando definido como `DifferentFromBuyer`, o grupo `recipient` na raiz passa a ser **obrigatório**. > **Preenchimento automático:** Em geral, você **não precisa** informar os subgrupos `ibs` e `cbs` com alíquotas e valores. Quando omitidos, o motor de cálculo da NFE.io os calcula automaticamente a partir do `operationIndicator`, do `classCode` e do `servicesAmount`. Informe-os apenas quando precisar sobrepor o cálculo automático. ### 1.1. Subgrupo: `ibs` (Opcional) Este subgrupo detalha o cálculo do IBS, que é um imposto subnacional (estadual e municipal). - `totalAmount`: O valor total do IBS para a operação (soma das parcelas estadual e municipal). - `state`: Detalhes da parcela **estadual** do IBS. - `municipal`: Detalhes da parcela **municipal** do IBS (mesma estrutura do subgrupo estadual). Tanto `state` quanto `municipal` (e também o `cbs`) compartilham a mesma estrutura de campos: | Campo | Descrição | |------------------|---------------------------------------------------------------------------| | `rate` | Alíquota de referência. | | `rateReduction` | Percentual de redução aplicado sobre a alíquota de referência. | | `effectiveRate` | Alíquota efetiva, após a redução. | | `deferment` | Informações de diferimento do tributo, quando aplicável. | | `returnedAmount` | Valor de tributo devolvido (cashback), quando aplicável. | | `amount` | Valor do tributo devido. | ### 1.2. Subgrupo: `cbs` (Opcional) Este subgrupo detalha o cálculo da CBS, que é um tributo federal. Possui a **mesma estrutura** dos subgrupos `ibs.state`/`ibs.municipal` (`rate`, `rateReduction`, `effectiveRate`, `deferment`, `returnedAmount`, `amount`). ### 1.3. Outros Subgrupos Opcionais no `ibsCbs`: O grupo `ibsCbs` também inclui outros subgrupos opcionais para tratar de cenários fiscais mais complexos, como: - `regularTaxation`: Para informar o cálculo hipotético do imposto no regime padrão. - `presumedCredits`: Para detalhar quaisquer créditos presumidos de IBS e CBS. - `governmentPurchase`: Para especificar detalhes fiscais para operações envolvendo entidades governamentais. - `creditTransfer`: Para casos que envolvem a transferência de créditos de IBS/CBS. - `thirdPartyReimbursements`: Para declarar valores relacionados a reembolsos ou repasses que não compõem a base de cálculo. - `relatedDocs`: Para referenciar outras NFS-e, permitindo vincular as chaves dos documentos relacionados. ## 2. Grupo: serviceAmountDetails (Opcional) Este grupo foi adicionado para fornecer uma decomposição mais clara dos valores cobrados, especialmente em cenários com multas e juros, comuns em contratos de serviço. Motivo da Inclusão: Para diferenciar o valor original do serviço de outros encargos, garantindo um cálculo mais preciso da base de cálculo. No layout anterior, esses valores eram frequentemente incluídos em `servicesAmount`. **Campos-chave:** - `initialChargedAmount`: O valor original cobrado pelo serviço, antes de quaisquer acréscimos. - `finalChargedAmount`: O valor final total cobrado, incluindo todos os impostos, multas e juros. - `fineAmount`: O valor específico referente a multas. - `interestAmount`: O valor específico referente a juros. ## 3. Outros Novos Campos e Grupos Além dos grupos principais acima, vários outros campos foram adicionados na raiz da requisição para acomodar o padrão nacional e fornecer mais detalhes. - `nbsCode` (string, obrigatório): Código da Nomenclatura Brasileira de Serviços. Esta é uma nova classificação obrigatória para serviços em nível nacional. - `ncmCode` (string, opcional): Código da Nomenclatura Comum do Mercosul, usado quando o serviço está relacionado a um bem físico. - `cnaeCode` (string, opcional): Código CNAE, exigido apenas quando o município o requer. - `paidAmount` (número, opcional): Valor total pago pelo serviço. - `accrualOn` (data, opcional): Data de competência da prestação do serviço. Se não for fornecida, será assumida a data de `issuedOn`. - `isEarlyInstallmentPayment` (booleano, opcional): Indica se a nota é para um pagamento de parcela antecipada. - `immunityType` (string, opcional): Especifica o tipo de imunidade tributária, se aplicável. - `retentionType` (string, opcional): Define quem é o responsável pela retenção do ISSQN (`NotWithheld`, `WithheldByBuyer`, `WithheldByIntermediary`). **Novos Campos de Alíquotas (Opcional):** O layout antigo possuía apenas campos (opcionais) para os valores finais dos impostos retidos. O novo layout inclui campos (opcionais) para as alíquotas, permitindo que o sistema utilize a alíquota informada pelo usuário no cálculo automático. - `pisRate` - `cofinsRate` **Novos Grupos Opcionais para Cenários Complexos:** Estes grupos foram adicionados para lidar com casos de negócio específicos previstos no padrão nacional. - `ReferenceSubstitution`: Usado quando uma nota está sendo emitida para substituir uma anterior. - `lease`: Para serviços envolvendo locação, sublocação ou direito de passagem de infraestrutura como ferrovias, postes e cabos. - `construction`: Para serviços de construção civil, exigindo a identificação da obra (CNO/CEI) ou o endereço do imóvel. - `foreignTrade`: Para operações de importação/exportação de serviços, detalhando aspectos como modo do serviço, moeda e mecanismos de fomento. - `intermediary`: Para identificar um intermediário na prestação do serviço, além do prestador e do tomador. - `recipient`: Para identificar o destinatário final do serviço quando ele é diferente do tomador. - `realEstate`: Para operações relacionadas a bens imóveis, exceto obras. - `deduction`: Para detalhar documentos que justificam deduções da base de cálculo (ex: subempreitadas). - `benefit`: Para aplicar um benefício fiscal municipal que reduz a base de cálculo do ISSQN. - `suspension`: Para indicar que a exigibilidade do ISSQN está suspensa por processo judicial ou administrativo. - `approximateTotals`: Uma versão mais detalhada do antigo `approximateTax`, decompondo a carga tributária aproximada nas esferas federal, estadual e municipal. ## Resumo das Principais Diferenças | Característica | Layout Antigo (antigo) | Novo Layout (novo) | |-------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | **Estrutura Tributária** | Baseada no ISS, com campos para retenções federais. | Centrada em **IBS** e **CBS**, com um grupo dedicado `ibsCbs`. | | **Grupo Principal de Imposto**| Não aplicável. Campos estavam no nível raiz. | **`ibsCbs`** (obrigatório), que contém todas as informações para os novos tributos. | | **Classificação do Serviço** | `cityServiceCode`, `federalServiceCode`. | Adiciona `nbsCode` (obrigatório) e `ncmCode` (opcional) para padronização nacional. | | **Cálculo de Impostos** | Mais simples, baseado em uma única alíquota de ISS. | Mais complexo, com cálculos separados para IBS estadual/municipal e CBS federal, incluindo alíquotas efetivas. | | **Cenários Especiais** | Tratados através de campos genéricos ou descrições. | Grupos específicos para `lease`, `construction`, `foreignTrade`, `ReferenceSubstitution`, etc. | | **Detalhamento de Valores** | Geralmente consolidado em `servicesAmount`. | O grupo `serviceAmountDetails` separa o valor original de multas e juros. | | **Participantes** | Apenas `borrower`. | Adiciona objetos opcionais `intermediary` e `recipient` para operações mais complexas. | ## Exemplo Mínimo (novo layout) O exemplo abaixo contém **apenas os campos obrigatórios** para emissão no novo layout — incluindo o grupo `ibsCbs` com `operationIndicator` e `classCode`. Os valores de IBS/CBS são calculados automaticamente pela plataforma. ```json { "borrower": { "name": "CONSUMIDOR MINIMO LTDA", "federalTaxNumber": 191 }, "cityServiceCode": "4444", "federalServiceCode": "01.01", "description": "Serviço de Consultoria e Assessoria.", "servicesAmount": 1000.00, "nbsCode": "101010100", "ibsCbs": { "operationIndicator": "1005011", "classCode": "000001" } } ``` `POST https://api.nfe.io/v1/companies/{company_id}/serviceinvoices` ## Referências - [Documentação Funcional do Layout de Emissão de NFS-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc) — detalhamento completo de todos os grupos e campos, tabelas de `operationIndicator` e `classCode`, e regras de validação. - [Referência da API — Emissão de NFS-e (RTC)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/api-de-emissao-de-nota-fiscal-de-servicos-eletronica-nfs-e-rtc/) — schema completo e exemplos (mínimo, intermediário e completo) diretamente no contrato OpenAPI. - [Envio de dados para emissão de NFS-e (RPS/DPS)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/envio-de-dados-para-emissao-de-nfs-e-rps-dps/) — endpoint de emissão. ## Conclusão A transição para o layout novo é impulsionada principalmente pela necessidade de adaptação ao novo modelo tributário da Reforma Tributária. O principal esforço de integração será o preenchimento correto do grupo `ibsCbs`, que exige um entendimento detalhado das novas regras fiscais aplicáveis a cada prestação de serviço. O restante do layout permanece em grande parte consistente com a versão anterior.