This endpoint allows you to retrieve the tax situation codes available for use in operations that require national tax information to be filled in the ibsCbs object.

This query is used to identify the valid values that can be informed in the ibsCbs.taxSituation field, helping to prevent inconsistencies during invoice issuance.

When to use

Retrieving tax situation codes is recommended when:

• your integration performs invoice issuance using the ibsCbs object;
• it is necessary to present a list of options to the user;
• there is a need to validate allowed codes beforehand;
• the application needs to keep the list of tax classifications provided by Asaas synchronized.

📘

Important

It is recommended to retrieve the available codes through the API instead of maintaining fixed values in the application.

How it works

This endpoint returns the tax situations available for use in the following field:

ibsCbs.taxSituation

The results can be filtered and paginated, allowing the creation of lists and search mechanisms in the application.

Dependency on the ibsCbs object

This endpoint is directly related to filling out invoice tax information.

The code returned by the query should later be used in the following field:

{
  "ibsCbs": {
    "taxSituation": "..."
  }
}

🚧

Important

The value informed in ibsCbs.taxSituation must correspond to a valid tax situation.

Incorrect or incompatible values may cause rejections or tax inconsistencies.

Query parameters

offset

Defines the starting position for pagination.

Example:

• offset = 0 → beginning of the list;
• offset = 100 → starts from the hundredth record.

limit

Defines the number of records returned per request.

Maximum limit:

100 records

code

Allows filtering a specific tax situation by its code.

This filter is recommended when the application needs to retrieve a known code.

description

Allows searching by the tax situation description.

It can be used to implement search mechanisms in the user interface.

Example usage

An application that issues invoices may follow the flow below:

Retrieve tax situation codes
↓
Display options to the user
↓
Select the appropriate classification
↓
Fill ibsCbs.taxSituation
↓
Issue the invoice

Important behaviors

📘

Important

This endpoint only provides the existing codes.

Selecting the correct tax situation depends on the tax rules applicable to the operation.

Additionally:

• different operations may require different classifications;
• the existence of a code does not necessarily mean that it applies to every scenario;
• the API may validate the compatibility of the information provided during the issuance process.

Best practices

📘

Recommended

• Retrieve the list of codes through the API instead of maintaining fixed values.
• Implement pagination using the offset and limit parameters.
• Store the codes locally only to optimize queries.
• Always validate the tax classification before issuing the invoice.
• Consult the applicable legislation and tax rules for the operation scenario.

Operational impacts

Choosing an incorrect tax situation may result in:

• tax inconsistencies;
• invoice issuance rejections;
• manual correction requirements;
• discrepancies in the document's tax information.

For this reason, it is recommended to validate the tax classification corresponding to the operation before issuing the invoice.

Next steps

After retrieving the tax situation codes, we recommend consulting:

• Invoice issuance.
• ibsCbs object.
• Tax settings.
• List related tax classifications.
• Create invoices.