# Consultar em lote Classifica até 100 itens numa requisição, com admissão e resultado item a item. Versão HTML: https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification-batch/ `POST /v1/classifications/batch` 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 até 100 itens numa requisição, um por um, na ordem enviada, e responde tudo na mesma resposta. Feito para carga e revisão de catálogo. Cada item tem os mesmos campos e regras da [consulta unitária](https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification.md), e cada `result` tem o mesmo formato da resposta dela. ### Admissão item a item - Um item inválido (GTIN com dígito verificador errado, setor desconhecido, campo não previsto) volta como `REJECTED` com `INVALID_REQUEST`, sem consumir franquia e sem derrubar os demais. - O lote inteiro só é recusado (HTTP 400) quando o envelope é inválido: `items` vazio ou com mais de 100 itens, campo além de `items`, ou item sem `gtin` e `cfop` em texto. - `index` aponta a posição do item no array enviado. Use-o para casar cada resultado com o seu item. ### Franquia - Cada item admitido consome uma unidade, GTIN repetido inclusive. No exemplo abaixo, o lote consome 2 unidades: o item de índice 1 foi recusado. - Se a franquia acabar no meio do lote, os itens já admitidos são mantidos e resolvidos; deste ponto em diante, todos voltam como `REJECTED` com `QUOTA_EXCEEDED`. O mesmo vale para `INVALID_API_KEY` e `SERVICE_UNAVAILABLE` na admissão: o item em que o erro ocorreu e todos os seguintes recebem esse erro. - Uma falha ao resolver um item já admitido afeta só aquele item (`SERVICE_UNAVAILABLE`); a unidade dele já foi consumida. ### O lote não busca na GS1 GTIN fora do catálogo volta `PENDING` com `LOCAL_PRODUCT_MISSING` e entra na fila de busca; consulte de novo mais tarde. Para tentar a GS1 na hora, use a consulta unitária. No lote não há `NOT_FOUND` por GTIN desconhecido. ### O que reenviar Reenvie só os itens `REJECTED` com `SERVICE_UNAVAILABLE` (com backoff) ou com `QUOTA_EXCEEDED` (depois da virada do mês). Itens `RESOLVED` já foram cobrados: reenviá-los consome de novo. Itens com `INVALID_REQUEST` precisam ser corrigidos antes. > [!NOTE] > Os valores fiscais dos exemplos são ilustrativos. ## Requisição Corpo JSON (`Content-Type: application/json`). - `items` (array, obrigatório) — Itens a classificar, de 1 a 100. Cada item é validado sozinho. Restrições: mínimo de 1 item · máximo de 100 itens. - `gtin` (string, obrigatório) — Código de barras do produto, com as mesmas regras da consulta unitária. Precisa ser texto: item sem `gtin` em texto invalida o lote inteiro (400). - `cfop` (string, obrigatório) — CFOP da operação, com 4 dígitos. Precisa ser texto: item sem `cfop` em texto invalida o lote inteiro (400). - `sector` (string, opcional) — Setor do cliente final, opcional. Valor fora da lista recusa só este item, com `INVALID_REQUEST`. - `referenceDate` (string, opcional) — Data (`AAAA-MM-DD`) para regras e alíquotas vigentes, opcional. Padrão: hoje, no fuso de São Paulo. ## Exemplo `$GETTAX_URL` é a base URL acima e `$GETTAX_KEY` a sua chave de API. ```shell curl -sS -X POST "$GETTAX_URL/v1/classifications/batch" \ -H "Authorization: Bearer $GETTAX_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "gtin": "7891000315507", "cfop": "5102" }, { "gtin": "7891000315508", "cfop": "5102" }, { "gtin": "7891000315521", "cfop": "5102", "sector": "VAREJO_GERAL" } ] }' ``` ## Respostas ### 200 · Lote processado, inclusive quando há itens recusados. O lote não responde 429: franquia esgotada aparece por item. Campos: - `results` (array, obrigatório) — Uma entrada por item enviado, na mesma ordem. - Uma das formas abaixo (`oneOf`): - **outcome = RESOLVED** - `outcome` (string, obrigatório) — `RESOLVED`: o item foi admitido e traz `result`. `REJECTED`: o item foi recusado e traz `error`. Valores: `RESOLVED`. - `index` (integer, obrigatório) — Posição do item no array enviado, começando em 0. Restrições: mínimo 0. - `result` (object, obrigatório) — Resposta do item, no mesmo formato da [consulta unitária](https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification.md). - `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`. - **outcome = REJECTED** - `outcome` (string, obrigatório) — `RESOLVED`: o item foi admitido e traz `result`. `REJECTED`: o item foi recusado e traz `error`. Valores: `REJECTED`. - `index` (integer, obrigatório) — Posição do item no array enviado, começando em 0. Restrições: mínimo 0. - `error` (string, obrigatório) — Por que o item foi recusado: `INVALID_REQUEST` (item inválido; não consome), `QUOTA_EXCEEDED` (franquia esgotada), `INVALID_API_KEY` (chave deixou de valer) ou `SERVICE_UNAVAILABLE` (falha temporária). Valores: `INVALID_REQUEST`, `QUOTA_EXCEEDED`, `INVALID_API_KEY`, `SERVICE_UNAVAILABLE`. Exemplo: ```json { "results": [ { "outcome": "RESOLVED", "index": 0, "result": { "decisionVersion": "4c5d6e7f-8091-4a2b-9c3d-4e5f60718293", "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" } } ] } }, { "outcome": "REJECTED", "index": 1, "error": "INVALID_REQUEST" }, { "outcome": "RESOLVED", "index": 2, "result": { "decisionVersion": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "status": "PENDING", "reason": "LOCAL_PRODUCT_MISSING", "gtin": "07891000315521", "cfop": "5102", "sector": "VAREJO_GERAL", "referenceDate": "2026-10-20", "product": null, "classifications": [] } } ] } ``` ### 400 · Envelope inválido: lote vazio, mais de 100 itens, campo além de `items`, item que não é objeto ou item sem `gtin`/`cfop` em texto. Nenhum item é processado nem consumido. 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" } ``` ### 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. 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" } ```