Este endpoint permite consultar os códigos de situações tributárias disponíveis para utilização em operações que exigem o preenchimento das informações tributárias nacionais no objeto ibsCbs.

A consulta é utilizada para identificar os valores válidos que podem ser informados no campo ibsCbs.taxSituation, evitando inconsistências durante a emissão fiscal.

Quando utilizar

A consulta dos códigos de situações tributárias é recomendada quando:

• sua integração realiza emissão fiscal utilizando o objeto ibsCbs;
• for necessário apresentar uma lista de opções ao usuário;
• houver necessidade de validar previamente os códigos permitidos;
• a aplicação precisar manter sincronizada a lista de classificações tributárias disponibilizadas pelo Asaas.

📘

Importante

Recomenda-se consultar os códigos disponíveis através da API em vez de manter valores fixos na aplicação.

Como funciona

O endpoint retorna as situações tributárias disponíveis para utilização no campo:

ibsCbs.taxSituation

Os resultados podem ser filtrados e paginados, permitindo a construção de listas e mecanismos de busca na aplicação.

Dependência com o objeto ibsCbs

Este endpoint possui relação direta com o preenchimento das informações tributárias da nota fiscal.

O código retornado pela consulta deverá ser utilizado posteriormente no campo:

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

🚧

Importante

O valor informado em ibsCbs.taxSituation deve corresponder a uma situação tributária válida.

O preenchimento incorreto ou incompatível com a operação pode causar rejeições ou inconsistências fiscais.

Parâmetros de consulta

offset

Define a posição inicial da paginação.

Exemplo:

• offset = 0 → início da listagem;
• offset = 100 → inicia a partir do centésimo registro.

limit

Define a quantidade de registros retornados por requisição.

Limite máximo:

100 registros

code

Permite filtrar uma situação tributária específica através do código.

Esse filtro é recomendado quando a aplicação precisa localizar apenas um código conhecido.

description

Permite pesquisar pela descrição da situação tributária.

Pode ser utilizado para implementar mecanismos de busca na interface do usuário.

Exemplo de utilização

Uma aplicação que realiza emissão de notas fiscais pode seguir o fluxo abaixo:

Consultar códigos de situações tributárias
↓
Exibir opções ao usuário
↓
Selecionar a classificação adequada
↓
Preencher ibsCbs.taxSituation
↓
Emitir a nota fiscal

Comportamentos importantes

📘

Importante

A consulta deste endpoint apenas disponibiliza os códigos existentes.

A escolha da situação tributária correta depende das regras fiscais aplicáveis à operação.

Além disso:

• diferentes operações podem exigir classificações distintas;
• a simples existência de um código não significa que ele seja aplicável a qualquer cenário;
• a API poderá validar a compatibilidade das informações enviadas durante o processo de emissão.

Boas práticas

📘

Recomendado

• Consulte a lista de códigos através da API em vez de manter valores fixos.
• Implemente paginação utilizando os parâmetros offset e limit.
• Armazene localmente os códigos apenas para otimizar consultas.
• Sempre valide a classificação tributária antes da emissão.
• Consulte a legislação e as regras fiscais aplicáveis ao cenário da operação.

Impactos operacionais

A escolha incorreta da situação tributária pode gerar:

• inconsistências fiscais;
• rejeições durante a emissão;
• necessidade de correção manual;
• divergências nas informações tributárias do documento.

Por esse motivo, recomenda-se validar a classificação tributária correspondente à operação antes da emissão.

Próximos passos

Após obter os códigos de situações tributárias, consulte:

• Emissão de notas fiscais.
• Objeto ibsCbs.
• Configurações fiscais.
• Listar classificações tributárias relacionadas.
• Criação de notas fiscais.