# Consultar classificação Classifica um produto (GTIN) para uma operação (CFOP) e devolve as alternativas de enquadramento de CBS e IBS. Versão HTML: https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification/ `POST /v1/classifications/resolve` Base URL: `https://app-web-hmg-01-api-gettax-hmg-dvawffg9g9cpcef3.brazilsouth-01.azurewebsites.net` (homologação). Autenticação: header `Authorization: Bearer `. [Como obter a chave](https://kind-coast-062131010.2.azurestaticapps.net/guias/autenticacao.md) Classifica um produto para uma operação, com as regras e alíquotas vigentes na data de referência. É a consulta do dia a dia: cadastro de um item novo, conferência antes da emissão, reclassificação de um produto específico. - **Todo resultado de negócio chega com HTTP 200.** O que aconteceu está em `status` e `reason`; trate os quatro casos. Ver [Status e alternativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md). - **Pode vir mais de uma alternativa** em `classifications`. A ordem não é recomendação: o emissor escolhe pela condição em `applicability`. - **GTIN fora do catálogo.** A consulta unitária pode buscar o produto na GS1 no momento da requisição, quando essa busca está ativa no ambiente. Se não conseguir, responde `PENDING`; respeite `retryAfterSeconds` quando vier. - **Franquia.** Cada consulta admitida consome uma unidade, qualquer que seja o status, GTIN repetido inclusive. Respostas 400 e 401 não consomem. Ver [Franquia e consumo](https://kind-coast-062131010.2.azurestaticapps.net/guias/franquia.md). Para classificar muitos itens de uma vez, use a [consulta em lote](https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification-batch.md). > [!NOTE] > Os valores fiscais dos exemplos (NCM, cClassTrib, alíquotas, fundamento legal) são ilustrativos. ## Requisição Corpo JSON (`Content-Type: application/json`). - `gtin` (string, obrigatório) — Código de barras do produto: só dígitos, com 8, 12, 13 ou 14 posições e dígito verificador válido. Sem máscara, espaços ou hífens. Restrições: padrão `^\d{8}$|^\d{12,14}$`. - `cfop` (string, obrigatório) — CFOP da operação, com 4 dígitos (ex.: `5102`). Obrigatório e sem valor padrão: o CST pode mudar com a operação. Ver [Dados da consulta](https://kind-coast-062131010.2.azurestaticapps.net/guias/dados-da-consulta.md#cfop). Restrições: padrão `^\d{4}$`. - `sector` (string, opcional) — Setor do cliente final. Ausente: todas as alternativas pertinentes. Informado: as genéricas mais as daquele setor. Omitir não equivale a `VAREJO_GERAL`. Valores: `VAREJO_GERAL`, `BAR_RESTAURANTE`, `PRODUTOR_RURAL`, `GOVERNO`, `ATACADO`, `ZONA_FRANCA`. - `referenceDate` (string, opcional) — Data (`AAAA-MM-DD`) usada para escolher regras e alíquotas vigentes. Padrão: hoje, no fuso de São Paulo. Restrições: data AAAA-MM-DD. ## Exemplo `$GETTAX_URL` é a base URL acima e `$GETTAX_KEY` a sua chave de API. ```shell curl -sS -X POST "$GETTAX_URL/v1/classifications/resolve" \ -H "Authorization: Bearer $GETTAX_KEY" \ -H "Content-Type: application/json" \ -d '{"gtin":"7891000315507","cfop":"5102"}' ``` ## Respostas ### 200 · Consulta processada. Os quatro status de negócio (`CLASSIFIED`, `PENDING`, `IN_REVIEW`, `NOT_FOUND`) chegam com 200. Campos: - `decisionVersion` (string, obrigatório) — Identificador da decisão, gravada em trilha de auditoria imutável. Cada consulta gera um novo, mesmo com a mesma entrada. Guarde junto do documento fiscal e informe ao reportar um problema. Restrições: UUID. - `status` (string, obrigatório) — Resultado da consulta: `CLASSIFIED`, `PENDING`, `IN_REVIEW` ou `NOT_FOUND`. Ver [Status e alternativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md). Valores: `CLASSIFIED`, `PENDING`, `IN_REVIEW`, `NOT_FOUND`. - `retryAfterSeconds` (integer, opcional) — Só em `PENDING`, quando a busca do produto foi adiada pelo limite diário de consultas do GetTax à GS1: segundos até esse limite reiniciar. Não consulte o mesmo GTIN antes disso. Ausente nos demais casos. Restrições: mínimo 0. - `reason` (string, obrigatório, pode ser null) — Motivo do status: `LOCAL_PRODUCT_MISSING` (produto fora do catálogo), `MISSING_NCM`, `MISSING_RULE` ou `INCOMPLETE_CLASSIFICATION`. `null` em `CLASSIFIED` e `NOT_FOUND`. Valores: `LOCAL_PRODUCT_MISSING`, `MISSING_NCM`, `MISSING_RULE`, `INCOMPLETE_CLASSIFICATION`. - `gtin` (string, obrigatório) — GTIN normalizado com 14 dígitos (zeros à esquerda). - `cfop` (string, obrigatório) — CFOP consultado. - `sector` (string, obrigatório, pode ser null) — Setor enviado; `null` quando a consulta não informou setor. Valores: `VAREJO_GERAL`, `BAR_RESTAURANTE`, `PRODUTOR_RURAL`, `GOVERNO`, `ATACADO`, `ZONA_FRANCA`. - `referenceDate` (string, obrigatório) — Data de referência efetivamente usada: a enviada ou a data de hoje em São Paulo. Restrições: data AAAA-MM-DD. - `product` (object, obrigatório, pode ser null) — Produto no catálogo do GetTax. `null` quando o GTIN não está no catálogo (`PENDING` e `NOT_FOUND`). - `id` (string, obrigatório) — Identificador interno do produto. Restrições: UUID. - `gtinAsProvided` (string, obrigatório, pode ser null) — GTIN na forma em que entrou no catálogo, antes da normalização para 14 dígitos. - `description` (string, obrigatório, pode ser null) — Descrição do produto, quando a origem informa. - `brand` (string, obrigatório, pode ser null) — Marca, quando a origem informa. - `ncm` (string, obrigatório, pode ser null) — NCM de 8 dígitos, sem pontuação. `null` quando a origem não informou. Sem NCM, só se aplicam regras que não dependem dele (por operação ou exceção por GTIN). - `ncmSource` (string, obrigatório, pode ser null) — Origem do NCM (hoje, `GS1`). `null` quando não há NCM. - `cest` (string, obrigatório, pode ser null) — CEST, quando a origem informa. - `gpcCode` (string, obrigatório, pode ser null) — Código de categoria GPC da GS1, quando informado. - `imageUrl` (string, obrigatório, pode ser null) — URL de imagem do produto, quando informada. - `sourceKind` (string, obrigatório) — Como o produto entrou no catálogo: `BULK` (carga de arquivo da GS1) ou `PROVIDER` (busca individual na GS1). - `classifications` (array, obrigatório) — Alternativas de enquadramento. Vazio quando não há alternativa. A ordem é técnica e estável, não recomendação: não escolha a primeira automaticamente. - `stage` (string, obrigatório) — Etapa do motor que produziu a alternativa: `OPERATION`, `COHERENCE`, `PRODUCT` ou `FALLBACK`. Ver [Etapas do motor](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md#etapas-do-motor). Valores: `OPERATION`, `COHERENCE`, `PRODUCT`, `FALLBACK`. - `rule` (object, obrigatório) — Regra curada que produziu a alternativa, com versão, vigência e escopo. - `id` (string, obrigatório) — Identificador da regra. Restrições: UUID. - `version` (integer, obrigatório) — Versão da regra. Junto com `rule.id`, identifica exatamente o que foi aplicado. - `effectiveFrom` (string, obrigatório) — Início da vigência da regra (inclusivo). Restrições: data AAAA-MM-DD. - `effectiveTo` (string, obrigatório, pode ser null) — Fim da vigência da regra (exclusivo). `null` = sem data de término. Restrições: data AAAA-MM-DD. - `ncm` (string, obrigatório, pode ser null) — Escopo de NCM da regra: família de 4 dígitos, NCM completo de 8, ou `null` quando a regra não depende de NCM. - `gtin` (string, obrigatório, pode ser null) — GTIN (14 dígitos) quando a regra é exceção para um produto específico; senão `null`. - `sector` (string, obrigatório, pode ser null) — Setor da regra. `null` = regra genérica, vale para qualquer setor. Valores: `VAREJO_GERAL`, `BAR_RESTAURANTE`, `PRODUTOR_RURAL`, `GOVERNO`, `ATACADO`, `ZONA_FRANCA`. - `cst` (string, obrigatório) — CST a informar no documento fiscal. É o mesmo para CBS e IBS. - `cClassTrib` (string, obrigatório) — Código de classificação tributária a informar no documento fiscal. É o mesmo para CBS e IBS. - `applicability` (string, obrigatório, pode ser null) — Condição em que a alternativa se aplica, em texto. `null` quando não há condição. Quem confirma se a condição vale para a operação é o emissor. - `observation` (string, obrigatório, pode ser null) — Observação da curadoria fiscal, em texto, ou `null`. - `legalBasis` (string, obrigatório, pode ser null) — Fundamento legal da alternativa: o da regra, quando a curadoria cadastrou um próprio; senão o do cClassTrib na fonte oficial (ex.: `LC 214/2025, Art. 135`). `null` quando nenhum dos dois existe. - `taxClassification` (object, obrigatório, pode ser null) — Linha da tabela oficial de cClassTrib usada no cálculo. `null` quando não há linha vigente para o código (o cálculo fica `UNAVAILABLE`). - `id` (string, obrigatório) — Identificador da linha na tabela de cClassTrib. Restrições: UUID. - `sourceVersion` (string, obrigatório) — Versão da fonte de onde a linha foi carregada. - `effectiveFrom` (string, obrigatório) — Início da vigência da linha (inclusivo). Restrições: data AAAA-MM-DD. - `effectiveTo` (string, obrigatório, pode ser null) — Fim da vigência da linha (exclusivo). `null` = sem data de término. Restrições: data AAAA-MM-DD. - `cst` (string, obrigatório) — CST do código na tabela oficial. Se divergir do CST da regra, o cálculo fica `UNAVAILABLE` com `CST_MISMATCH`. - `cClassTrib` (string, obrigatório) — Código cClassTrib da linha. - `reductionPctIbs` (string, obrigatório) — Redução do IBS (vale para `IBS_UF` e `IBS_MUN`), fração decimal em string, com 6 casas: `0.600000` = 60%. - `reductionPctCbs` (string, obrigatório) — Redução da CBS, fração decimal em string, com 6 casas: `0.600000` = 60%. - `gTribRegular` (boolean, obrigatório) — Indicador `gTribRegular` do código, como publicado na tabela oficial de cClassTrib. - `isApplicable` (boolean, obrigatório) — Indicador de aplicabilidade do código, como publicado na tabela oficial de cClassTrib. - `calculationMode` (string, obrigatório) — Como o código é calculado: `STANDARD` (alíquota × (1 − redução)), `NOT_DUE` (sem tributo devido) ou `UNSUPPORTED` (mecânica que o motor ainda não calcula, como diferimento e monofasia). Valores: `STANDARD`, `NOT_DUE`, `UNSUPPORTED`. - `legalBasis` (string, obrigatório, pode ser null) — Fundamento legal do código na fonte oficial. O que vale para a alternativa é o `legalBasis` dela. - `rates` (array, obrigatório) — Linhas da tabela de alíquotas vigentes na data de referência, uma por componente. - `id` (string, obrigatório) — Identificador da linha na tabela de alíquotas. Restrições: UUID. - `sourceVersion` (string, obrigatório) — Versão da fonte de onde a alíquota foi carregada. - `effectiveFrom` (string, obrigatório) — Início da vigência da alíquota (inclusivo). Restrições: data AAAA-MM-DD. - `effectiveTo` (string, obrigatório, pode ser null) — Fim da vigência da alíquota (exclusivo). `null` = sem data de término. Restrições: data AAAA-MM-DD. - `component` (string, obrigatório) — Componente a que a alíquota se refere. Valores: `CBS`, `IBS_UF`, `IBS_MUN`. - `rate` (string, obrigatório) — Alíquota padrão do componente, fração decimal em string, com 6 casas: `0.009000` = 0,9%. - `components` (array, obrigatório, pode ser null) — Resultado por componente (`CBS`, `IBS_UF`, `IBS_MUN`). `null` quando o cálculo está indisponível (`calculation.status = UNAVAILABLE`). Ver [Componentes e alíquotas](https://kind-coast-062131010.2.azurestaticapps.net/guias/componentes-e-aliquotas.md). - Uma das formas abaixo (`oneOf`): - **status = STANDARD** - `component` (string, obrigatório) — Componente: `CBS`, `IBS_UF` ou `IBS_MUN`. Trate a lista como aberta: novos componentes podem surgir. Valores: `CBS`, `IBS_UF`, `IBS_MUN`. - `cst` (string, obrigatório) — CST do componente. Igual ao da alternativa. - `cClassTrib` (string, obrigatório) — cClassTrib do componente. Igual ao da alternativa. - `status` (string, obrigatório) — `STANDARD`: tributo devido, com alíquota padrão, redução e alíquota efetiva. `NOT_DUE`: sem tributo devido; não traz números. Valores: `STANDARD`. - `standardRate` (string, obrigatório) — Alíquota padrão do componente na data de referência, fração decimal em string, com 6 casas. - `reductionPct` (string, obrigatório) — Redução aplicada ao componente, fração decimal em string, com 6 casas. - `effectiveRate` (string, obrigatório) — Alíquota efetiva: `standardRate × (1 − reductionPct)`, fração decimal em string, com 6 casas. - **status = NOT_DUE** - `component` (string, obrigatório) — Componente: `CBS`, `IBS_UF` ou `IBS_MUN`. Trate a lista como aberta: novos componentes podem surgir. Valores: `CBS`, `IBS_UF`, `IBS_MUN`. - `cst` (string, obrigatório) — CST do componente. Igual ao da alternativa. - `cClassTrib` (string, obrigatório) — cClassTrib do componente. Igual ao da alternativa. - `status` (string, obrigatório) — `STANDARD`: tributo devido, com alíquota padrão, redução e alíquota efetiva. `NOT_DUE`: sem tributo devido; não traz números. Valores: `NOT_DUE`. - `calculation` (um de, obrigatório) — Estado do cálculo da alternativa. Uma alternativa sem cálculo continua na resposta, com o motivo. - Uma das formas abaixo (`oneOf`): - **status = CALCULATED** - `status` (string, obrigatório) — `CALCULATED` (componentes `STANDARD`), `NOT_DUE` (componentes `NOT_DUE`) ou `UNAVAILABLE` (`components` nulo). Valores: `CALCULATED`. - **status = NOT_DUE** - `status` (string, obrigatório) — `CALCULATED` (componentes `STANDARD`), `NOT_DUE` (componentes `NOT_DUE`) ou `UNAVAILABLE` (`components` nulo). Valores: `NOT_DUE`. - **status = UNAVAILABLE** - `status` (string, obrigatório) — `CALCULATED` (componentes `STANDARD`), `NOT_DUE` (componentes `NOT_DUE`) ou `UNAVAILABLE` (`components` nulo). Valores: `UNAVAILABLE`. - `reason` (string, obrigatório) — Só em `UNAVAILABLE`: `TAX_CLASSIFICATION_MISSING`, `CST_MISMATCH`, `RATE_MISSING` ou `CALCULATION_UNSUPPORTED`. Valores: `TAX_CLASSIFICATION_MISSING`, `CST_MISMATCH`, `RATE_MISSING`, `CALCULATION_UNSUPPORTED`. Exemplo: ```json { "decisionVersion": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "status": "CLASSIFIED", "reason": null, "gtin": "07891000315507", "cfop": "5102", "sector": null, "referenceDate": "2026-10-20", "product": { "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "gtinAsProvided": "7891000315507", "description": "ARROZ BRANCO TIPO 1 5KG", "brand": "MARCA EXEMPLO", "ncm": "10063021", "ncmSource": "GS1", "cest": null, "gpcCode": null, "imageUrl": null, "sourceKind": "BULK" }, "classifications": [ { "stage": "PRODUCT", "rule": { "id": "3f6b2c1e-8a4d-4f2b-9c7e-1d2a3b4c5d6e", "version": 1, "effectiveFrom": "2026-01-01", "effectiveTo": null, "ncm": "1006", "gtin": null, "sector": null }, "cst": "200", "cClassTrib": "200034", "applicability": "Venda para alimentação humana.", "observation": null, "legalBasis": "LC 214/2025, Art. 135", "taxClassification": { "id": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0", "sourceVersion": "CCLASSTRIB-2026", "effectiveFrom": "2026-01-01", "effectiveTo": null, "cst": "200", "cClassTrib": "200034", "reductionPctIbs": "0.600000", "reductionPctCbs": "0.600000", "gTribRegular": false, "isApplicable": true, "calculationMode": "STANDARD", "legalBasis": "LC 214/2025, Art. 135" }, "rates": [ { "id": "0b1c2d3e-4f50-4a61-8b72-c3d4e5f60718", "sourceVersion": "ALIQUOTAS-2026", "effectiveFrom": "2026-01-01", "effectiveTo": null, "component": "CBS", "rate": "0.009000" }, { "id": "1c2d3e4f-5061-4b72-9c83-d4e5f6071829", "sourceVersion": "ALIQUOTAS-2026", "effectiveFrom": "2026-01-01", "effectiveTo": null, "component": "IBS_UF", "rate": "0.001000" }, { "id": "2d3e4f50-6172-4c83-ad94-e5f60718293a", "sourceVersion": "ALIQUOTAS-2026", "effectiveFrom": "2026-01-01", "effectiveTo": null, "component": "IBS_MUN", "rate": "0.000000" } ], "components": [ { "component": "CBS", "cst": "200", "cClassTrib": "200034", "status": "STANDARD", "standardRate": "0.009000", "reductionPct": "0.600000", "effectiveRate": "0.003600" }, { "component": "IBS_UF", "cst": "200", "cClassTrib": "200034", "status": "STANDARD", "standardRate": "0.001000", "reductionPct": "0.600000", "effectiveRate": "0.000400" }, { "component": "IBS_MUN", "cst": "200", "cClassTrib": "200034", "status": "STANDARD", "standardRate": "0.000000", "reductionPct": "0.600000", "effectiveRate": "0.000000" } ], "calculation": { "status": "CALCULATED" } } ] } ``` ### 400 · Corpo inválido: JSON malformado, campo obrigatório ausente, GTIN fora do formato ou com dígito verificador errado, CFOP sem 4 dígitos, setor desconhecido, data inválida ou campo não previsto. Não consome franquia. Campos: - `error` (string, obrigatório) — Código do erro, sem mensagem detalhada. Ver [Erros e novas tentativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/erros.md). Valores: `INVALID_REQUEST`. Exemplo: ```json { "error": "INVALID_REQUEST" } ``` ### 401 · Chave ausente, malformada, inexistente, revogada ou de cliente desativado. Não consome franquia. Campos: - `error` (string, obrigatório) — Código do erro, sem mensagem detalhada. Ver [Erros e novas tentativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/erros.md). Valores: `INVALID_API_KEY`. Exemplo: ```json { "error": "INVALID_API_KEY" } ``` ### 429 · Franquia mensal esgotada. As consultas voltam a ser aceitas na virada do mês (horário de Brasília). Campos: - `error` (string, obrigatório) — Código do erro, sem mensagem detalhada. Ver [Erros e novas tentativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/erros.md). Valores: `QUOTA_EXCEEDED`. Exemplo: ```json { "error": "QUOTA_EXCEEDED" } ``` ### 500 · Erro inesperado. Repita com backoff exponencial. Campos: - `error` (string, obrigatório) — Código do erro, sem mensagem detalhada. Ver [Erros e novas tentativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/erros.md). Valores: `INTERNAL_ERROR`. Exemplo: ```json { "error": "INTERNAL_ERROR" } ``` ### 503 · Serviço temporariamente indisponível. Se a falha ocorreu depois da admissão, a unidade da franquia já foi consumida. Repita com backoff exponencial. Campos: - `error` (string, obrigatório) — Código do erro, sem mensagem detalhada. Ver [Erros e novas tentativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/erros.md). Valores: `SERVICE_UNAVAILABLE`. Exemplo: ```json { "error": "SERVICE_UNAVAILABLE" } ```