Consultar classificação
Classifica um produto (GTIN) para uma operação (CFOP) e devolve as alternativas de enquadramento de CBS e IBS.
/v1/classifications/resolveAutenticação: Authorization: Bearer <sua chave>. Como obter a chave
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
statusereason; trate os quatro casos. Ver Status e alternativas. - Pode vir mais de uma alternativa em
classifications. A ordem não é recomendação: o emissor escolhe pela condição emapplicability. - 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; respeiteretryAfterSecondsquando 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.
Para classificar muitos itens de uma vez, use a consulta em lote.
Nota
Os valores fiscais dos exemplos (NCM, cClassTrib, alíquotas, fundamento legal) são ilustrativos.
Requisição
Corpo JSON (Content-Type: application/json).
gtinstringobrigatórioCó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.padrão
^\d{8}$|^\d{12,14}$cfopstringobrigatórioCFOP 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.padrão
^\d{4}$sectorstringSetor do cliente final. Ausente: todas as alternativas pertinentes. Informado: as genéricas mais as daquele setor. Omitir não equivale aVAREJO_GERAL.Valores:VAREJO_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCAreferenceDatestringData (AAAA-MM-DD) usada para escolher regras e alíquotas vigentes. Padrão: hoje, no fuso de São Paulo.data AAAA-MM-DD
Exemplos
curl -sS -X POST "$GETTAX_URL/v1/classifications/resolve" \ -H "Authorization: Bearer $GETTAX_KEY" \ -H "Content-Type: application/json" \ -d '{"gtin":"7891000315507","cfop":"5102"}'// Node 18+ (fetch nativo). Rode com: node gettax.mjsconst response = await fetch(`${process.env.GETTAX_URL}/v1/classifications/resolve`, { method: "POST", headers: { Authorization: `Bearer ${process.env.GETTAX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ gtin: "7891000315507", cfop: "5102", }),}); const data = await response.json();if (!response.ok) throw new Error(`GetTax ${response.status}: ${data.error}`);console.log(data);import os import requests # pip install requests response = requests.post( f"{os.environ['GETTAX_URL']}/v1/classifications/resolve", headers={"Authorization": f"Bearer {os.environ['GETTAX_KEY']}"}, json={ "gtin": "7891000315507", "cfop": "5102", }, timeout=30,)response.raise_for_status()print(response.json())// .NET 7+ (top-level statements). Rode com: dotnet runusing System.Net.Http.Headers;using System.Text; var baseUrl = Environment.GetEnvironmentVariable("GETTAX_URL");var apiKey = Environment.GetEnvironmentVariable("GETTAX_KEY"); using var http = new HttpClient();http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); var body = """ { "gtin": "7891000315507", "cfop": "5102" } """;using var content = new StringContent(body, Encoding.UTF8, "application/json");using var response = await http.PostAsync($"{baseUrl}/v1/classifications/resolve", content); Console.WriteLine((int)response.StatusCode);Console.WriteLine(await response.Content.ReadAsStringAsync());// Java 17+. Rode com: java GetTax.javaimport java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse; public class GetTax { public static void main(String[] args) throws Exception { var baseUrl = System.getenv("GETTAX_URL"); var apiKey = System.getenv("GETTAX_KEY"); var body = """ { "gtin": "7891000315507", "cfop": "5102" } """; var request = HttpRequest.newBuilder(URI.create(baseUrl + "/v1/classifications/resolve")) .header("Authorization", "Bearer " + apiKey) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); }}<?php// PHP 8+ com a extensão curl. Rode com: php gettax.php$ch = curl_init(getenv('GETTAX_URL') . '/v1/classifications/resolve');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('GETTAX_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'gtin' => '7891000315507', 'cfop' => '5102', ]),]); $body = curl_exec($ch);if ($body === false) { throw new RuntimeException(curl_error($ch));} echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), PHP_EOL, $body, PHP_EOL;// Delphi XE8+ (System.Net.HttpClient, sem componentes de terceiros).program GetTax; {$APPTYPE CONSOLE} uses System.SysUtils, System.Classes, System.Net.HttpClient, System.Net.URLClient; const Body = '{' + ' "gtin": "7891000315507",' + ' "cfop": "5102"' + '}'; var Client: THTTPClient; Content: TStringStream; Response: IHTTPResponse;begin Client := THTTPClient.Create; Content := TStringStream.Create(Body, TEncoding.UTF8); try Response := Client.Post(GetEnvironmentVariable('GETTAX_URL') + '/v1/classifications/resolve', Content, nil, [ TNetHeader.Create('Authorization', 'Bearer ' + GetEnvironmentVariable('GETTAX_KEY')), TNetHeader.Create('Content-Type', 'application/json') ]); Writeln(Response.StatusCode); Writeln(Response.ContentAsString(TEncoding.UTF8)); finally Content.Free; Client.Free; end;end.Respostas
200Consulta processada. Os quatro status de negócio (CLASSIFIED, PENDING, IN_REVIEW, NOT_FOUND) chegam com 200.›
decisionVersionstringobrigatórioIdentificador 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.UUID
statusstringobrigatórioValores:CLASSIFIEDPENDINGIN_REVIEWNOT_FOUNDretryAfterSecondsintegerSó emPENDING, 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.mínimo 0
reasonstringobrigatóriopode ser nullMotivo do status:LOCAL_PRODUCT_MISSING(produto fora do catálogo),MISSING_NCM,MISSING_RULEouINCOMPLETE_CLASSIFICATION.nullemCLASSIFIEDeNOT_FOUND.Valores:LOCAL_PRODUCT_MISSINGMISSING_NCMMISSING_RULEINCOMPLETE_CLASSIFICATIONgtinstringobrigatórioGTIN normalizado com 14 dígitos (zeros à esquerda).cfopstringobrigatórioCFOP consultado.sectorstringobrigatóriopode ser nullSetor enviado;nullquando a consulta não informou setor.Valores:VAREJO_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCAreferenceDatestringobrigatórioData de referência efetivamente usada: a enviada ou a data de hoje em São Paulo.data AAAA-MM-DD
productobjectobrigatóriopode ser nullProduto no catálogo do GetTax.nullquando o GTIN não está no catálogo (PENDINGeNOT_FOUND).›10 campos
idstringobrigatórioIdentificador interno do produto.UUID
gtinAsProvidedstringobrigatóriopode ser nullGTIN na forma em que entrou no catálogo, antes da normalização para 14 dígitos.descriptionstringobrigatóriopode ser nullDescrição do produto, quando a origem informa.brandstringobrigatóriopode ser nullMarca, quando a origem informa.ncmstringobrigatóriopode ser nullNCM de 8 dígitos, sem pontuação.nullquando a origem não informou. Sem NCM, só se aplicam regras que não dependem dele (por operação ou exceção por GTIN).ncmSourcestringobrigatóriopode ser nullOrigem do NCM (hoje,GS1).nullquando não há NCM.ceststringobrigatóriopode ser nullCEST, quando a origem informa.gpcCodestringobrigatóriopode ser nullCódigo de categoria GPC da GS1, quando informado.imageUrlstringobrigatóriopode ser nullURL de imagem do produto, quando informada.sourceKindstringobrigatórioComo o produto entrou no catálogo:BULK(carga de arquivo da GS1) ouPROVIDER(busca individual na GS1).
classificationsarray<object>obrigatórioAlternativas 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.›11 campos
stagestringobrigatórioEtapa do motor que produziu a alternativa:OPERATION,COHERENCE,PRODUCTouFALLBACK. Ver Etapas do motor.Valores:OPERATIONCOHERENCEPRODUCTFALLBACKruleobjectobrigatórioRegra curada que produziu a alternativa, com versão, vigência e escopo.›7 campos
idstringobrigatórioIdentificador da regra.UUID
versionintegerobrigatórioVersão da regra. Junto comrule.id, identifica exatamente o que foi aplicado.effectiveFromstringobrigatórioInício da vigência da regra (inclusivo).data AAAA-MM-DD
effectiveTostringobrigatóriopode ser nullFim da vigência da regra (exclusivo).null= sem data de término.data AAAA-MM-DD
ncmstringobrigatóriopode ser nullEscopo de NCM da regra: família de 4 dígitos, NCM completo de 8, ounullquando a regra não depende de NCM.gtinstringobrigatóriopode ser nullGTIN (14 dígitos) quando a regra é exceção para um produto específico; senãonull.sectorstringobrigatóriopode ser nullSetor da regra.null= regra genérica, vale para qualquer setor.Valores:VAREJO_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCA
cststringobrigatórioCST a informar no documento fiscal. É o mesmo para CBS e IBS.cClassTribstringobrigatórioCódigo de classificação tributária a informar no documento fiscal. É o mesmo para CBS e IBS.applicabilitystringobrigatóriopode ser nullCondição em que a alternativa se aplica, em texto.nullquando não há condição. Quem confirma se a condição vale para a operação é o emissor.observationstringobrigatóriopode ser nullObservação da curadoria fiscal, em texto, ounull.legalBasisstringobrigatóriopode ser nullFundamento 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).nullquando nenhum dos dois existe.taxClassificationobjectobrigatóriopode ser nullLinha da tabela oficial de cClassTrib usada no cálculo.nullquando não há linha vigente para o código (o cálculo ficaUNAVAILABLE).›12 campos
idstringobrigatórioIdentificador da linha na tabela de cClassTrib.UUID
sourceVersionstringobrigatórioVersão da fonte de onde a linha foi carregada.effectiveFromstringobrigatórioInício da vigência da linha (inclusivo).data AAAA-MM-DD
effectiveTostringobrigatóriopode ser nullFim da vigência da linha (exclusivo).null= sem data de término.data AAAA-MM-DD
cststringobrigatórioCST do código na tabela oficial. Se divergir do CST da regra, o cálculo ficaUNAVAILABLEcomCST_MISMATCH.cClassTribstringobrigatórioCódigo cClassTrib da linha.reductionPctIbsstringobrigatórioRedução do IBS (vale paraIBS_UFeIBS_MUN), fração decimal em string, com 6 casas:0.600000= 60%.reductionPctCbsstringobrigatórioRedução da CBS, fração decimal em string, com 6 casas:0.600000= 60%.gTribRegularbooleanobrigatórioIndicadorgTribRegulardo código, como publicado na tabela oficial de cClassTrib.isApplicablebooleanobrigatórioIndicador de aplicabilidade do código, como publicado na tabela oficial de cClassTrib.calculationModestringobrigatórioComo o código é calculado:STANDARD(alíquota × (1 − redução)),NOT_DUE(sem tributo devido) ouUNSUPPORTED(mecânica que o motor ainda não calcula, como diferimento e monofasia).Valores:STANDARDNOT_DUEUNSUPPORTEDlegalBasisstringobrigatóriopode ser nullFundamento legal do código na fonte oficial. O que vale para a alternativa é olegalBasisdela.
ratesarray<object>obrigatórioLinhas da tabela de alíquotas vigentes na data de referência, uma por componente.›6 campos
idstringobrigatórioIdentificador da linha na tabela de alíquotas.UUID
sourceVersionstringobrigatórioVersão da fonte de onde a alíquota foi carregada.effectiveFromstringobrigatórioInício da vigência da alíquota (inclusivo).data AAAA-MM-DD
effectiveTostringobrigatóriopode ser nullFim da vigência da alíquota (exclusivo).null= sem data de término.data AAAA-MM-DD
componentstringobrigatórioComponente a que a alíquota se refere.Valores:CBSIBS_UFIBS_MUNratestringobrigatórioAlíquota padrão do componente, fração decimal em string, com 6 casas:0.009000= 0,9%.
componentsarray<um de>obrigatóriopode ser nullResultado por componente (CBS,IBS_UF,IBS_MUN).nullquando o cálculo está indisponível (calculation.status = UNAVAILABLE). Ver Componentes e alíquotas.›2 formas possíveis
status = STANDARD
componentstringobrigatórioComponente:CBS,IBS_UFouIBS_MUN. Trate a lista como aberta: novos componentes podem surgir.Valores:CBSIBS_UFIBS_MUNcststringobrigatórioCST do componente. Igual ao da alternativa.cClassTribstringobrigatóriocClassTrib do componente. Igual ao da alternativa.statusstringobrigatórioSTANDARD: tributo devido, com alíquota padrão, redução e alíquota efetiva.NOT_DUE: sem tributo devido; não traz números.Valores:STANDARDstandardRatestringobrigatórioAlíquota padrão do componente na data de referência, fração decimal em string, com 6 casas.reductionPctstringobrigatórioRedução aplicada ao componente, fração decimal em string, com 6 casas.effectiveRatestringobrigatórioAlíquota efetiva:standardRate × (1 − reductionPct), fração decimal em string, com 6 casas.
status = NOT_DUE
componentstringobrigatórioComponente:CBS,IBS_UFouIBS_MUN. Trate a lista como aberta: novos componentes podem surgir.Valores:CBSIBS_UFIBS_MUNcststringobrigatórioCST do componente. Igual ao da alternativa.cClassTribstringobrigatóriocClassTrib do componente. Igual ao da alternativa.statusstringobrigatórioSTANDARD: 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
calculationum deobrigatórioEstado do cálculo da alternativa. Uma alternativa sem cálculo continua na resposta, com o motivo.›3 formas possíveis
status = CALCULATED
statusstringobrigatórioCALCULATED(componentesSTANDARD),NOT_DUE(componentesNOT_DUE) ouUNAVAILABLE(componentsnulo).Valores:CALCULATED
status = NOT_DUE
statusstringobrigatórioCALCULATED(componentesSTANDARD),NOT_DUE(componentesNOT_DUE) ouUNAVAILABLE(componentsnulo).Valores:NOT_DUE
status = UNAVAILABLE
statusstringobrigatórioCALCULATED(componentesSTANDARD),NOT_DUE(componentesNOT_DUE) ouUNAVAILABLE(componentsnulo).Valores:UNAVAILABLEreasonstringobrigatórioSó emUNAVAILABLE:TAX_CLASSIFICATION_MISSING,CST_MISMATCH,RATE_MISSINGouCALCULATION_UNSUPPORTED.Valores:TAX_CLASSIFICATION_MISSINGCST_MISMATCHRATE_MISSINGCALCULATION_UNSUPPORTED
{ "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" } } ]}400Corpo 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.›
errorstringobrigatórioCódigo do erro, sem mensagem detalhada. Ver Erros e novas tentativas.Valores:INVALID_REQUEST
{ "error": "INVALID_REQUEST"}401Chave ausente, malformada, inexistente, revogada ou de cliente desativado. Não consome franquia.›
errorstringobrigatórioCódigo do erro, sem mensagem detalhada. Ver Erros e novas tentativas.Valores:INVALID_API_KEY
{ "error": "INVALID_API_KEY"}429Franquia mensal esgotada. As consultas voltam a ser aceitas na virada do mês (horário de Brasília).›
errorstringobrigatórioCódigo do erro, sem mensagem detalhada. Ver Erros e novas tentativas.Valores:QUOTA_EXCEEDED
{ "error": "QUOTA_EXCEEDED"}500Erro inesperado. Repita com backoff exponencial.›
errorstringobrigatórioCódigo do erro, sem mensagem detalhada. Ver Erros e novas tentativas.Valores:INTERNAL_ERROR
{ "error": "INTERNAL_ERROR"}503Serviço temporariamente indisponível. Se a falha ocorreu depois da admissão, a unidade da franquia já foi consumida. Repita com backoff exponencial.›
errorstringobrigatórioCódigo do erro, sem mensagem detalhada. Ver Erros e novas tentativas.Valores:SERVICE_UNAVAILABLE
{ "error": "SERVICE_UNAVAILABLE"}