Configure PIS/COFINS when issuing NFS-e

The NT-007 rules change how PIS and COFINS are filled in for Regime Normal customers when issuing NFS-e.

Since Jun 30, 2026, use pisCofinsTaxStatus, operationPis, and operationCofins according to the tax status of the operation. The pisCofinsRetentionType field is calculated by Asaas and must not be sent by the integration.

Simples Nacional customers do not need to change the payload because of NT-007.

How to configure

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Retrieve tax information"] --> B{"Is simplesNacional true?"}

    B --> Sim(("Yes"))
    B --> Nao(("No"))

    Sim --> C["Keep Simples Nacional rules"]
    Nao --> D["Validate the applicable CST"]

    D --> E["Set pisCofinsTaxStatus"]
    E --> F["Provide operationPis and operationCofins"]
    F --> G["Provide withholdings, if any"]

    C --> H["Issue the NFS-e"]
    G --> H
    H --> I["Track via Webhook"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B decisao
    class C,D,E,F,G,H validacao
    class I sucesso

    class Sim respostaSim
    class Nao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

PIS/COFINS fields

Distinguish operation rate from withholding

The fields have different purposes:

pisCofinsTaxStatus determines which values can be sent in operationPis and operationCofins.

Withholding percentages do not replace operation rates.

pisCofinsTaxStatus values

Use the tax status that corresponds to the operation.

Fill in operationPis and operationCofins

NT-007 sets specific rules for some tax statuses:

For the other values, NT-007 does not set a specific restriction for operationPis and operationCofins. Fill them in according to the tax situation of the operation.

Provide withholdings, when applicable

Use:

• pis;
• cofins;
• csll.

Asaas calculates pisCofinsRetentionType from these percentages.

Examples

Taxable operation with basic rate

{
  "taxes": {
    "pisCofinsTaxStatus": "STANDARD_TAXABLE_OPERATION",
    "operationPis": 0.65,
    "operationCofins": 3.00,
    "pis": 0.65,
    "cofins": 3.00,
    "csll": 1.00
  }
}

operationPis and operationCofins represent the operation rates. pis, cofins, and csll represent the withholdings.

Taxable operation at zero rate

{
  "taxes": {
    "pisCofinsTaxStatus": "ZERO_RATE_TAXABLE_OPERATION",
    "operationPis": 0,
    "operationCofins": 0,
    "pis": null,
    "cofins": null,
    "csll": null
  }
}

For ZERO_RATE_TAXABLE_OPERATION, send operationPis and operationCofins as 0.

Exempt operation

{
  "taxes": {
    "pisCofinsTaxStatus": "EXEMPT_CONTRIBUTION_OPERATION",
    "operationPis": null,
    "operationCofins": null,
    "pis": null,
    "cofins": null,
    "csll": null
  }
}

For EXEMPT_CONTRIBUTION_OPERATION, send operationPis and operationCofins as null.

Tax status not defined

{
  "taxes": {
    "pisCofinsTaxStatus": "NONE",
    "operationPis": null,
    "operationCofins": null,
    "pis": null,
    "cofins": null,
    "csll": null
  }
}

Consider CST normalization

In these situations:

• TAXABLE_PER_MEASURE_UNIT_OPERATION;
• MONOPHASIC_RESALE_ZERO_RATE_OPERATION;
• TAX_SUBSTITUTION_OPERATION;

Asaas may return pisCofinsTaxStatus as NONE when all PIS and COFINS percentages are zero or null.

Prepare your parser for the returned value to differ from the one sent in these scenarios.

Common errors

Example when the required tax status is not provided:

{
  "errors": [
    {
      "description": "The PIS/COFINS tax status is required"
    }
  ]
}

Where to apply

The rules must be considered when sending or updating NFS-e tax data, including:

POST /v3/invoices
PUT /v3/invoices/{id}

They also apply to the automatic invoice issuing configuration for subscriptions:

POST /v3/subscriptions/{id}/invoiceSettings
PUT /v3/subscriptions/{id}/invoiceSettings

See the complete contracts in the API Reference:

• Schedule invoice
• Update invoice
• Create configuration for issuance of Invoices
• Update configuration for issuance of Invoices

Validate the issuance

After sending the NFS-e, track the result via Webhooks instead of repeatedly querying the status.

Mainly handle:

• INVOICE_AUTHORIZED, when the invoice is issued;
• INVOICE_ERROR, when there is an issuing error.

See the events for invoices.

Runnable example

For a specific example of this configuration, see:

Configure PIS/COFINS retention and tax status

Next steps

• See the NT-007 changes
• Issue service invoices
• Configure automatic issuing for subscriptions
• Track invoice events