Conceitos

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.

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.

Atenção

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

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

IN_REVIEW por falta de NCM:

json

1{
2  "decisionVersion": "9d0e1f2a-3b4c-4d5e-af60-7b8c9d0e1f2a",
3  "status": "IN_REVIEW",
4  "reason": "MISSING_NCM",
5  "gtin": "07898357410015",
6  "cfop": "5102",
7  "sector": "VAREJO_GERAL",
8  "referenceDate": "2026-10-20",
9  "product": {
10    "id": "0e1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b",
11    "gtinAsProvided": "7898357410015",
12    "description": "BISCOITO EXEMPLO 200G",
13    "brand": "MARCA EXEMPLO",
14    "ncm": null,
15    "ncmSource": null,
16    "cest": null,
17    "gpcCode": null,
18    "imageUrl": null,
19    "sourceKind": "BULK"
20  },
21  "classifications": []
22}

NOT_FOUND:

json

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

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.

Importante

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.

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.