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
REJECTEDcomQUOTA_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
PENDINGem loop. Cada nova consulta consome. RespeiteretryAfterSecondse espace as tentativas. Ver Status e alternativas. - Não reenvie itens de lote já resolvidos. Reenvie só os
REJECTEDcomSERVICE_UNAVAILABLEouQUOTA_EXCEEDED. - Valide a chave com a lista de setores, que não consome, e não com uma consulta.