Adequando sua integração à Reforma Tributária

A Reforma Tributária substitui gradualmente PIS/COFINS pela CBS e ICMS/ISS pelo IBS.

Na emissão de Notas Fiscais de Serviço (NFS-e), sua integração deve estar preparada para enviar as novas classificações fiscais exigidas no objeto taxes quando aplicáveis à operação — incluindo, para serviços de bens imóveis, os campos adicionais exigidos pela reforma.

Quando utilizar

• Sua empresa emite NFS-e sujeitas às novas regras fiscais da Reforma Tributária (IBS/CBS).
• Sua empresa presta serviços de locação, cessão onerosa, arrendamento, administração ou intermediação de bens imóveis.

Antes de começar

• Integração de agendamento de NFS-e já funcionando (Agendar nota fiscal)
• Configuração fiscal da conta concluída
• Identificar o regime tributário da empresa e a data de obrigatoriedade aplicável
• Levantar se algum dos serviços prestados envolve bens imóveis

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Validar regime e obrigatoriedade"] --> B["Consultar códigos fiscais"]
    B --> C["Preencher taxes"]
    C --> D["Agendar a NFS-e"]
    D --> E["Receber Webhook"]
    E --> F["Confirmar o resultado"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Para serviços de bens imóveis, o passo "Preencher taxes" inclui também os campos operationTypeCode, referencedInvoiceAccessKeyList e realEstateInfo, detalhados no passo a passo abaixo.

Passo a passo

Passo 1 – Valide o regime e a obrigatoriedade da empresa

O cronograma varia conforme o tipo de documento e o regime tributário:

Valide o enquadramento fiscal da empresa e da operação antes de decidir quando enviar os novos campos.

Passo 2 – Consulte os códigos fiscais válidos

Não mantenha códigos tributários fixos na integração. Consulte os valores disponíveis pela API e utilize a classificação aplicável à operação:

• federalServiceTaxCode corresponde ao Código de Tributação Nacional. Não é enviado dentro de taxes — é configurado previamente no cadastro do serviço municipal (veja em Campos importantes, abaixo).

A escolha do código correto depende das regras fiscais aplicáveis ao serviço e à operação. Para taxClassificationCode, utilize a situação tributária correspondente para localizar as classificações relacionadas.

Passo 3 – Preencha o objeto taxes e agende a NFS-e

Endpoint: POST /v3/invoices

Quando os dados da Reforma Tributária forem exigidos, inclua taxes no payload da emissão.

{
  "payment": "pay_637959110194",
  "municipalServiceName": "Análise e desenvolvimento de sistemas",
  "value": 300,
  "effectiveDate": "2026-10-01",
  "taxes": {
    "nbsCode": "<CODIGO_NBS>",
    "taxSituationCode": "<SITUACAO_TRIBUTARIA>",
    "taxClassificationCode": "<CLASSIFICACAO_TRIBUTARIA>",
    "operationIndicatorCode": "<INDICADOR_OPERACAO>"
  }
}

Não copie os valores de um exemplo para Produção. Consulte os códigos válidos e selecione aqueles correspondentes à operação emitida.

Passo 4 – Inclua os campos de bens imóveis, quando aplicável

Para serviços de locação, cessão onerosa, arrendamento, administração ou intermediação de bens imóveis, taxes também aceita:

• operationTypeCode → tipo de operação praticada (valores de 1 a 5), aceito apenas quando o federalServiceTaxCode do serviço iniciar com 25.05, 15.09, 17.12 ou 10.05
• referencedInvoiceAccessKeyList → chaves de acesso das NFS-e já emitidas e referenciadas por esta nota, obrigatório quando operationTypeCode for 2 ou 3
• realEstateInfo → dados do imóvel (identificação, endereço e CEP), obrigatório ou não permitido conforme o federalServiceTaxCode e o operationIndicatorCode do serviço

Consulte as regras completas de obrigatoriedade, os códigos válidos e as mensagens de erro em Agendar nota fiscal.

{
  "payment": "pay_637959110194",
  "municipalServiceName": "Locação de imóvel comercial",
  "value": 3000,
  "effectiveDate": "2026-10-01",
  "taxes": {
    "nbsCode": "<CODIGO_NBS>",
    "taxSituationCode": "<SITUACAO_TRIBUTARIA>",
    "taxClassificationCode": "<CLASSIFICACAO_TRIBUTARIA>",
    "operationIndicatorCode": "020101",
    "operationTypeCode": 2,
    "referencedInvoiceAccessKeyList": ["<CHAVE_NFSE_REFERENCIADA>"],
    "realEstateInfo": {
      "cibCode": "<CODIGO_CIB>",
      "address": "<ENDERECO>",
      "addressNumber": "<NUMERO>",
      "province": "<BAIRRO>",
      "postalCode": "<CEP>"
    }
  }
}

Passo 5 – Acompanhe o resultado pelo Webhook

A emissão da NFS-e é assíncrona. Utilize Webhooks para acompanhar o resultado em vez de consultar repetidamente o status pela API.

Trate principalmente:

• INVOICE_AUTHORIZED, quando a nota for emitida
• INVOICE_ERROR, quando houver erro no processamento

Consulte os eventos de Webhook para notas fiscais.

Campos importantes

Atenção — duplicidade / erros comuns

• Não copie valores de exemplo (placeholders) para Produção — utilize sempre os códigos consultados pela API para a operação real.
• Evite manter códigos tributários fixos no código da integração; eles podem mudar conforme a prefeitura ou o tipo de serviço.
• Não envie os campos de bens imóveis para serviços ou indicadores de operação que não os exigem — isso gera rejeição da nota.

Confirme o resultado

Checklist pós-execução:

• Os códigos enviados existem nas respectivas listagens
• taxClassificationCode corresponde à situação tributária utilizada
• O indicador da operação corresponde ao serviço prestado
• Os dados fiscais utilizados estão de acordo com o regime da empresa
• Para serviços de bens imóveis, operationTypeCode, referencedInvoiceAccessKeyList e realEstateInfo foram preenchidos conforme exigido
• A nota é processada sem rejeição fiscal

Boas práticas

• Se o seu software possui cadastro de serviços ou produtos, adicione campos para armazenar o Código NBS e o Código de Tributação Nacional (federalServiceTaxCode) de cada item.
• Durante a emissão, pode ser necessário solicitar ao usuário que selecione a Situação Tributária, caso ela varie por operação.
• Implemente uma lógica no seu código para enviar o objeto taxes apenas quando a empresa emissora estiver sujeita às novas regras, garantindo compatibilidade com a regra de transição.
• Para optantes pelo Simples Nacional, valide a integração antes da entrada em vigor das regras de IBS/CBS em 01/01/2027.

Referência da API

Próximos passos

• Emita notas fiscais de serviço
• Configure a emissão automática para assinaturas
• Acompanhe os eventos de notas fiscais
• Configure retenção e situação tributária de PIS/COFINS
• Adequar a emissão de Nota Fiscal à Reforma Tributária (IBS/CBS) (Recipe)