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.
ImportanteRecomenda-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.taxSituationOs 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": "..."
}
}
ImportanteO valor informado em
ibsCbs.taxSituationdeve 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 registroscode
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 fiscalComportamentos importantes
ImportanteA 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
offsetelimit.- 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.
403Forbidden. Ocorre quando o body da requisição está preenchido, chamadas de método GET precisam ter um body vazio.
