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 classificações nacionais exigidas no objeto ibsCbs quando elas forem aplicáveis à operação.

Quando a adequação passa a ser obrigatória

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.

Como adaptar a integração

%%{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 ibsCbs"]
    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

Consulte os códigos antes da emissão

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:

A escolha do código correto depende das regras fiscais aplicáveis ao serviço e à operação.

Para taxClassification, utilize a situação tributária correspondente para localizar as classificações relacionadas.

Preencha o objeto ibsCbs

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

Exemplo:

{
  "payment": "pay_637959110194",
  "municipalServiceName": "Análise e desenvolvimento de sistemas",
  "value": 300,
  "effectiveDate": "2026-10-01",
  "ibsCbs": {
    "nbsCode": "<CODIGO_NBS>",
    "nationalServiceCode": "<CODIGO_SERVICO_NACIONAL>",
    "taxSituation": "<SITUACAO_TRIBUTARIA>",
    "taxClassification": "<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.

Campos do objeto

A recomendação acima considera a regra de transição vigente em 2026. Para optantes pelo Simples Nacional, valide a integração antes da entrada em vigor das regras de IBS/CBS em 01/01/2027.

Endpoints impactados

A adequação deve ser considerada principalmente nos fluxos que definem os dados fiscais utilizados na emissão.

Emissão avulsa ou vinculada a cobrança

POST /v3/invoices

Consulte o endpoint Agendar nota fiscal.

Emissão automática para assinaturas

POST /v3/subscriptions/{id}/invoiceSettings

Consulte o endpoint Criar configuração para emissão de Notas Fiscais.

Valide a emissão

Teste o cenário aplicável à empresa antes de utilizar Produção.

Confirme que:

• os códigos enviados existem nas respectivas listagens;
• taxClassification 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;
• a nota é processada sem rejeição fiscal.

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.

Exemplo completo

Para executar a adequação com consultas e exemplos de payload, consulte:

Adequar a emissão de Nota Fiscal à Reforma Tributária (IBS/CBS).

Próximos passos

• Emita notas fiscais de serviço
• Consulte o endpoint Agendar nota fiscal
• 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