# Franquia e consumo

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

Versão HTML: https://kind-coast-062131010.2.azurestaticapps.net/guias/franquia/

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](https://app-web-05-prd-wl-gettax-prd.azurewebsites.net), 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](https://kind-coast-062131010.2.azurestaticapps.net/guias/boas-praticas.md#reaproveite-as-respostas).
- **Não repita `PENDING` em loop.** Cada nova consulta consome. Respeite `retryAfterSeconds` e espace as tentativas. Ver [Status e alternativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md#produto-fora-do-catalogo).
- **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.