Conceitos

Franquia e consumo

O que consome a franquia mensal de consultas, o que não consome e o que acontece quando ela acaba.

Cada software house tem uma franquia mensal de consultas, definida no plano. A franquia é da software house, não da chave: todas as chaves dela consomem do mesmo saldo. O mês é o mês-calendário no fuso de São Paulo: o contador recomeça às 00h00 do dia 1º, horário de Brasília.

O que consome#

Uma consulta consome uma unidade quando é admitida: a chave é válida, o corpo é válido e ainda há franquia. A partir daí, a unidade está gasta, qualquer que seja o resultado.

Consome uma unidade	Não consome
Cada consulta admitida em `POST /v1/classifications/resolve`.	`GET /v1/enums/sectors`.
Cada item admitido em `POST /v1/classifications/batch`: um lote de 40 itens válidos consome 40.	Requisições recusadas na validação (`400`).
GTIN repetido, no mesmo lote ou em requisições diferentes.	Requisições recusadas na autenticação (`401`).
Consultas com qualquer status: `CLASSIFIED`, `PENDING`, `IN_REVIEW` ou `NOT_FOUND`.	Itens do lote recusados com `INVALID_REQUEST`.
Consultas admitidas que falham depois (`503`): a unidade já tinha sido reservada.	Itens do lote recusados com `QUOTA_EXCEEDED` depois que a franquia acabou.

Quando a franquia acaba#

Consulta unitária: HTTP 429 com {"error": "QUOTA_EXCEEDED"}.
Lote: HTTP 200. Os itens admitidos antes do limite são mantidos e resolvidos; os restantes voltam como REJECTED com QUOTA_EXCEEDED. O lote nunca responde 429.

As consultas voltam a ser aceitas na virada do mês. Para ampliar a franquia antes disso, fale com a equipe GetTax.

Onde acompanhar o consumo#

A API não devolve o saldo em cabeçalho nem em rota própria. O consumo fica no portal da revenda, em Consumo:

a franquia do mês: quanto já foi usado, quanto resta e quando renova;
as consultas por dia;
as consultas recentes, com GTIN, CFOP, setor e status de cada uma.

O detalhe das consultas fica disponível pelos últimos 12 meses.

Como gastar menos#

Reaproveite as respostas. A classificação depende de GTIN, CFOP, setor e data de referência, não do seu cliente final. Guarde a resposta no seu banco com essa chave e reutilize entre os seus clientes, em vez de consultar de novo a cada venda. Ver Boas práticas.
Não repita PENDING em loop. Cada nova consulta consome. Respeite retryAfterSeconds e espace as tentativas. Ver Status e alternativas.
Não reenvie itens de lote já resolvidos. Reenvie só os REJECTED com SERVICE_UNAVAILABLE ou QUOTA_EXCEEDED.
Valide a chave com a lista de setores, que não consome, e não com uma consulta.