Adapting your integration to the Tax Reform

The Tax Reform gradually replaces PIS/COFINS with CBS and ICMS/ISS with IBS.

When issuing Service Invoices (NFS-e), your integration must be ready to send the new tax classifications required in the taxes object when they apply to the operation — including, for real estate services, the additional fields required by the reform.

When to use

• Your company issues NFS-e subject to the new Tax Reform rules (IBS/CBS).
• Your company provides real estate rental, paid assignment, leasing, management, or brokerage services.

Before you start

• NFS-e scheduling integration already working (Schedule invoice)
• Account tax configuration completed
• Identify the company tax regime and the applicable mandatory start date
• Check whether any of the services provided involve real estate

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Validate regime and requirement"] --> B["Look up tax codes"]
    B --> C["Fill in taxes"]
    C --> D["Schedule the NFS-e"]
    D --> E["Receive Webhook"]
    E --> F["Confirm the result"]

    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

For real estate services, the "Fill in taxes" step also includes the operationTypeCode, referencedInvoiceAccessKeyList, and realEstateInfo fields, detailed in the step by step below.

Step by step

Step 1 – Validate the company regime and requirement

The schedule varies according to the document type and the tax regime:

Validate the tax classification of the company and the operation before deciding when to send the new fields.

Step 2 – Look up the valid tax codes

Do not hardcode tax codes in the integration. Look up the available values through the API and use the classification that applies to the operation:

• federalServiceTaxCode corresponds to the National Taxation Code. It is not sent inside taxes — it is configured beforehand in the municipal service registration (see Important fields, below).

Choosing the right code depends on the tax rules that apply to the service and the operation. For taxClassificationCode, use the corresponding tax situation to find the related classifications.

Step 3 – Fill in the taxes object and schedule the NFS-e

Endpoint: POST /v3/invoices

When Tax Reform data is required, include taxes in the issuing payload.

{
  "payment": "pay_637959110194",
  "municipalServiceName": "Systems analysis and development",
  "value": 300,
  "effectiveDate": "2026-10-01",
  "taxes": {
    "nbsCode": "<NBS_CODE>",
    "taxSituationCode": "<TAX_SITUATION>",
    "taxClassificationCode": "<TAX_CLASSIFICATION>",
    "operationIndicatorCode": "<OPERATION_INDICATOR>"
  }
}

Do not copy values from an example into Production. Look up the valid codes and select the ones that match the operation being invoiced.

Step 4 – Include the real estate fields, when applicable

For real estate rental, paid assignment, leasing, management, or brokerage services, taxes also accepts:

• operationTypeCode → type of operation performed (values from 1 to 5), accepted only when the service federalServiceTaxCode starts with 25.05, 15.09, 17.12, or 10.05
• referencedInvoiceAccessKeyList → access keys of NFS-e already issued and referenced by this invoice, required when operationTypeCode is 2 or 3
• realEstateInfo → property data (identification, address, and postal code), required or not allowed depending on the service federalServiceTaxCode and operationIndicatorCode

See the full requirement rules, valid codes, and error messages in Schedule invoice.

{
  "payment": "pay_637959110194",
  "municipalServiceName": "Commercial property rental",
  "value": 3000,
  "effectiveDate": "2026-10-01",
  "taxes": {
    "nbsCode": "<NBS_CODE>",
    "taxSituationCode": "<TAX_SITUATION>",
    "taxClassificationCode": "<TAX_CLASSIFICATION>",
    "operationIndicatorCode": "020101",
    "operationTypeCode": 2,
    "referencedInvoiceAccessKeyList": ["<REFERENCED_NFSE_KEY>"],
    "realEstateInfo": {
      "cibCode": "<CIB_CODE>",
      "address": "<ADDRESS>",
      "addressNumber": "<NUMBER>",
      "province": "<DISTRICT>",
      "postalCode": "<POSTAL_CODE>"
    }
  }
}

Step 5 – Track the result via Webhook

NFS-e issuance is asynchronous. Use Webhooks to track the result instead of repeatedly querying the status through the API.

Mainly handle:

• INVOICE_AUTHORIZED, when the invoice is issued
• INVOICE_ERROR, when there is a processing error

See the Webhook events for invoices.

Important fields

Attention — duplication / common errors

• Do not copy example values (placeholders) into Production — always use the codes looked up through the API for the real operation.
• Avoid hardcoding tax codes in the integration code; they may change depending on the city hall or the type of service.
• Do not send the real estate fields for services or operation indicators that do not require them — this causes the invoice to be rejected.

Confirm the result

Post-execution checklist:

• The codes sent exist in their respective listings
• taxClassificationCode matches the tax situation used
• The operation indicator matches the service provided
• The tax data used matches the company regime
• For real estate services, operationTypeCode, referencedInvoiceAccessKeyList e realEstateInfo were filled in as required
• The invoice is processed without tax rejection

Best practices

• If your software has a service or product registry, add fields to store the NBS Code and the National Taxation Code (federalServiceTaxCode) for each item.
• During issuance, you may need to ask the user to select the Tax Situation if it varies by operation.
• Implement logic in your code to send the taxes object only when the issuing company is subject to the new rules, ensuring compatibility with the transition rule.
• For Simples Nacional companies, validate the integration before the IBS/CBS rules take effect on Jan 1, 2027.

API Reference

Next steps

• Issue service invoices
• Configure automatic issuing for subscriptions
• Track invoice events
• Configure PIS/COFINS retention and tax status
• Adapt Invoice issuance to the Tax Reform (IBS/CBS) (Recipe)