# Status e alternativas

Como ler o resultado de uma consulta, o que fazer em cada status e por que nunca escolher uma alternativa pela posição.

Versão HTML: https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas/

Toda consulta processada responde HTTP 200. O que aconteceu está em dois campos: `status` diz o resultado, `reason` diz o motivo. As alternativas de enquadramento vêm em `classifications`.

## Status

| `status` | `reason` | Quando | O que fazer |
| --- | --- | --- | --- |
| `CLASSIFIED` | `null` | Produto conhecido e todas as alternativas com resultado (`CALCULATED` ou `NOT_DUE`). | Use as alternativas, respeitando `applicability`. Guarde o `decisionVersion` com o documento. |
| `PENDING` | `LOCAL_PRODUCT_MISSING` | O GTIN não está no catálogo e a busca do produto ainda não concluiu. | Consulte de novo mais tarde. Se vier `retryAfterSeconds`, espere pelo menos esse tempo. |
| `IN_REVIEW` | `MISSING_NCM` | O produto está no catálogo sem NCM, e nenhuma regra que dispense o NCM se aplicou. | Não presuma tributação integral. O caso vai para a curadoria fiscal; consulte de novo depois. |
| `IN_REVIEW` | `MISSING_RULE` | O produto tem NCM, mas não há regra vigente para ele com esse CFOP (e setor). | Idem: curadoria fiscal, nova consulta depois. |
| `IN_REVIEW` | `INCOMPLETE_CLASSIFICATION` | Há alternativas, mas pelo menos uma está sem cálculo (`UNAVAILABLE`) ou é um alerta de coerência (`stage: COHERENCE`). | Não emita automaticamente. As alternativas calculadas são informativas; encaminhe para revisão. |
| `NOT_FOUND` | `null` | A GS1 informou que o GTIN não existe. Só na consulta unitária. | Confira o código de barras no cadastro do item. |

Sem classificação concluída, nunca preencha o documento com tributação integral por conta própria. A ausência de regra não quer dizer que o produto é tributado integralmente: quer dizer que ninguém decidiu ainda.

## Produto fora do catálogo

O catálogo do GetTax é formado por produtos da GS1. Quando o GTIN ainda não está lá:

- **Consulta unitária**: o GetTax pode buscar o produto na GS1 no momento da requisição, quando essa busca está ativa no ambiente. Se encontrar, classifica na mesma resposta. Se não conseguir concluir, responde `PENDING`. Se a GS1 informar que o GTIN não existe, responde `NOT_FOUND`; essa resposta fica guardada por um período (hoje, 7 dias) e é repetida sem nova busca.
- **Lote**: nunca busca na GS1. GTIN fora do catálogo volta `PENDING` e entra na fila de busca.

`retryAfterSeconds` só aparece em `PENDING`, quando a busca foi adiada porque o limite diário de consultas do GetTax à GS1 acabou. É o número de segundos até esse limite reiniciar.

> [!WARNING]
> Não repita a consulta em loop. Toda consulta admitida consome franquia, inclusive as que respondem `PENDING`. Depois de uma falha da GS1, o GetTax espera um intervalo antes de tentar de novo, então repetir antes disso só gasta franquia. Se um GTIN continuar `PENDING` por dias, fale com a equipe GetTax.

`PENDING` por limite diário da GS1:

```json
{
  "decisionVersion": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "status": "PENDING",
  "retryAfterSeconds": 41520,
  "reason": "LOCAL_PRODUCT_MISSING",
  "gtin": "07891000315521",
  "cfop": "5102",
  "sector": null,
  "referenceDate": "2026-10-20",
  "product": null,
  "classifications": []
}
```

`IN_REVIEW` por falta de NCM:

```json
{
  "decisionVersion": "9d0e1f2a-3b4c-4d5e-af60-7b8c9d0e1f2a",
  "status": "IN_REVIEW",
  "reason": "MISSING_NCM",
  "gtin": "07898357410015",
  "cfop": "5102",
  "sector": "VAREJO_GERAL",
  "referenceDate": "2026-10-20",
  "product": {
    "id": "0e1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b",
    "gtinAsProvided": "7898357410015",
    "description": "BISCOITO EXEMPLO 200G",
    "brand": "MARCA EXEMPLO",
    "ncm": null,
    "ncmSource": null,
    "cest": null,
    "gpcCode": null,
    "imageUrl": null,
    "sourceKind": "BULK"
  },
  "classifications": []
}
```

`NOT_FOUND`:

```json
{
  "decisionVersion": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "status": "NOT_FOUND",
  "reason": null,
  "gtin": "07891234567895",
  "cfop": "5102",
  "sector": null,
  "referenceDate": "2026-10-20",
  "product": null,
  "classifications": []
}
```

`NOT_FOUND` no corpo de uma resposta 200 não é o mesmo que HTTP 404, que indica rota inexistente.

## Alternativas

Mais de uma alternativa é normal. Acontece quando existe regra genérica e regra do setor, ou quando o mesmo produto tem cClassTribs diferentes para condições diferentes (por exemplo, conforme o regime do destinatário). Nenhuma alternativa é descartada só porque outra é mais específica.

> [!IMPORTANT]
> A ordem das alternativas não é recomendação fiscal. É técnica e estável (por etapa, depois por código), para a resposta não mudar entre execuções. Nunca escolha a primeira automaticamente.

Cada alternativa traz:

- `cst` e `cClassTrib`: o par que vai no documento fiscal, igual para CBS e IBS.
- `applicability`: a condição em que a alternativa se aplica, em texto, ou `null`.
- `observation`: um alerta ou contexto da curadoria, ou `null`.
- `legalBasis`: o fundamento legal.
- `components` e `calculation`: as alíquotas por componente. Ver [Componentes e alíquotas](https://kind-coast-062131010.2.azurestaticapps.net/guias/componentes-e-aliquotas.md).

O GetTax não recebe o regime do emitente nem detalhes da operação além do CFOP. Quem confirma se a condição de uma alternativa vale para a operação é o emissor: uma pessoa, ou uma regra de negócio explícita do seu sistema que avalie a condição. Com uma única alternativa sem condição, não há o que escolher.

## Etapas do motor

`stage` diz qual etapa produziu a alternativa. As etapas são percorridas nesta ordem:

| Etapa | O que faz |
| --- | --- |
| `OPERATION` | A operação (CFOP) resolve sozinha, sem depender do produto. Se houver regra desta etapa, a classificação termina aqui, sem passar pelas etapas seguintes. |
| `COHERENCE` | Alerta de incoerência entre produto e operação, por exemplo um combustível vendido com CFOP genérico de venda. Acrescenta alternativas às de `PRODUCT`; nunca resolve sozinha. Torna o status `IN_REVIEW`. |
| `PRODUCT` | Classificação pelo produto: família de NCM (4 dígitos), NCM completo (8 dígitos) ou exceção cadastrada para um GTIN. |
| `FALLBACK` | Regra de contingência cadastrada explicitamente pela curadoria. Só entra quando `PRODUCT` não resolve e o produto tem NCM. |

Não existe classificação padrão implícita: se nenhuma regra se aplica, o resultado é `IN_REVIEW`, nunca uma alíquota cheia presumida.

## Versões e vigências

Cada alternativa diz de onde veio cada peça:

- `rule.id` e `rule.version`: a regra curada aplicada.
- `taxClassification`: a linha da tabela oficial de cClassTrib, com `sourceVersion`.
- `rates[]`: as linhas da tabela de alíquotas, uma por componente, com `sourceVersion`.

Todas têm vigência `[effectiveFrom, effectiveTo)`. Guarde esses campos com o documento emitido: é o que permite explicar depois de onde veio cada número. Ver [Boas práticas](https://kind-coast-062131010.2.azurestaticapps.net/guias/boas-praticas.md#guarde-a-decisao-com-o-documento).