GetTax, powered by SAC Fiscal

Referência da API

Consultar classificação

Classifica um produto (GTIN) para uma operação (CFOP) e devolve as alternativas de enquadramento de CBS e IBS.

post/v1/classifications/resolve

Autenticaçã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 status e reason; 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 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.

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ó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.

    padrão ^\d{8}$|^\d{12,14}$

  • cfopstringobrigató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.

    padrão ^\d{4}$

  • sectorstring
    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_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCA
  • referenceDatestring
    Data (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

Terminal
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

200Consulta processada. Os quatro status de negócio (CLASSIFIED, PENDING, IN_REVIEW, NOT_FOUND) chegam com 200.›
  • decisionVersionstringobrigató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.

    UUID

  • statusstringobrigatório
    Resultado da consulta: CLASSIFIED, PENDING, IN_REVIEW ou NOT_FOUND. Ver Status e alternativas.
    Valores:CLASSIFIEDPENDINGIN_REVIEWNOT_FOUND
  • retryAfterSecondsinteger
    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.

    mínimo 0

  • reasonstringobrigatóriopode 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_MISSINGMISSING_NCMMISSING_RULEINCOMPLETE_CLASSIFICATION
  • gtinstringobrigatório
    GTIN normalizado com 14 dígitos (zeros à esquerda).
  • cfopstringobrigatório
    CFOP consultado.
  • sectorstringobrigatóriopode ser null
    Setor enviado; null quando a consulta não informou setor.
    Valores:VAREJO_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCA
  • referenceDatestringobrigatório
    Data de referência efetivamente usada: a enviada ou a data de hoje em São Paulo.

    data AAAA-MM-DD

  • productobjectobrigatóriopode ser null
    Produto no catálogo do GetTax. null quando o GTIN não está no catálogo (PENDING e NOT_FOUND).
    ›10 campos
    • idstringobrigatório
      Identificador interno do produto.

      UUID

    • gtinAsProvidedstringobrigatóriopode ser null
      GTIN na forma em que entrou no catálogo, antes da normalização para 14 dígitos.
    • descriptionstringobrigatóriopode ser null
      Descrição do produto, quando a origem informa.
    • brandstringobrigatóriopode ser null
      Marca, quando a origem informa.
    • ncmstringobrigatóriopode 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).
    • ncmSourcestringobrigatóriopode ser null
      Origem do NCM (hoje, GS1). null quando não há NCM.
    • ceststringobrigatóriopode ser null
      CEST, quando a origem informa.
    • gpcCodestringobrigatóriopode ser null
      Código de categoria GPC da GS1, quando informado.
    • imageUrlstringobrigatóriopode ser null
      URL de imagem do produto, quando informada.
    • sourceKindstringobrigatório
      Como o produto entrou no catálogo: BULK (carga de arquivo da GS1) ou PROVIDER (busca individual na GS1).
  • classificationsarray<object>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.
    ›11 campos
    • stagestringobrigatório
      Etapa do motor que produziu a alternativa: OPERATION, COHERENCE, PRODUCT ou FALLBACK. Ver Etapas do motor.
      Valores:OPERATIONCOHERENCEPRODUCTFALLBACK
    • ruleobjectobrigatório
      Regra curada que produziu a alternativa, com versão, vigência e escopo.
      ›7 campos
      • idstringobrigatório
        Identificador da regra.

        UUID

      • versionintegerobrigatório
        Versão da regra. Junto com rule.id, identifica exatamente o que foi aplicado.
      • effectiveFromstringobrigatório
        Início da vigência da regra (inclusivo).

        data AAAA-MM-DD

      • effectiveTostringobrigatóriopode ser null
        Fim da vigência da regra (exclusivo). null = sem data de término.

        data AAAA-MM-DD

      • ncmstringobrigatóriopode 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.
      • gtinstringobrigatóriopode ser null
        GTIN (14 dígitos) quando a regra é exceção para um produto específico; senão null.
      • sectorstringobrigatóriopode ser null
        Setor da regra. null = regra genérica, vale para qualquer setor.
        Valores:VAREJO_GERALBAR_RESTAURANTEPRODUTOR_RURALGOVERNOATACADOZONA_FRANCA
    • cststringobrigatório
      CST a informar no documento fiscal. É o mesmo para CBS e IBS.
    • cClassTribstringobrigatório
      Código de classificação tributária a informar no documento fiscal. É o mesmo para CBS e IBS.
    • applicabilitystringobrigatóriopode 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.
    • observationstringobrigatóriopode ser null
      Observação da curadoria fiscal, em texto, ou null.
    • legalBasisstringobrigatóriopode 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.
    • taxClassificationobjectobrigatóriopode 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).
      ›12 campos
      • idstringobrigatório
        Identificador da linha na tabela de cClassTrib.

        UUID

      • sourceVersionstringobrigatório
        Versão da fonte de onde a linha foi carregada.
      • effectiveFromstringobrigatório
        Início da vigência da linha (inclusivo).

        data AAAA-MM-DD

      • effectiveTostringobrigatóriopode ser null
        Fim da vigência da linha (exclusivo). null = sem data de término.

        data AAAA-MM-DD

      • cststringobrigatório
        CST do código na tabela oficial. Se divergir do CST da regra, o cálculo fica UNAVAILABLE com CST_MISMATCH.
      • cClassTribstringobrigatório
        Código cClassTrib da linha.
      • reductionPctIbsstringobrigatório
        Redução do IBS (vale para IBS_UF e IBS_MUN), fração decimal em string, com 6 casas: 0.600000 = 60%.
      • reductionPctCbsstringobrigatório
        Redução da CBS, fração decimal em string, com 6 casas: 0.600000 = 60%.
      • gTribRegularbooleanobrigatório
        Indicador gTribRegular do código, como publicado na tabela oficial de cClassTrib.
      • isApplicablebooleanobrigatório
        Indicador de aplicabilidade do código, como publicado na tabela oficial de cClassTrib.
      • calculationModestringobrigató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:STANDARDNOT_DUEUNSUPPORTED
      • legalBasisstringobrigatóriopode ser null
        Fundamento legal do código na fonte oficial. O que vale para a alternativa é o legalBasis dela.
    • ratesarray<object>obrigatório
      Linhas da tabela de alíquotas vigentes na data de referência, uma por componente.
      ›6 campos
      • idstringobrigatório
        Identificador da linha na tabela de alíquotas.

        UUID

      • sourceVersionstringobrigatório
        Versão da fonte de onde a alíquota foi carregada.
      • effectiveFromstringobrigatório
        Início da vigência da alíquota (inclusivo).

        data AAAA-MM-DD

      • effectiveTostringobrigatóriopode ser null
        Fim da vigência da alíquota (exclusivo). null = sem data de término.

        data AAAA-MM-DD

      • componentstringobrigatório
        Componente a que a alíquota se refere.
        Valores:CBSIBS_UFIBS_MUN
      • ratestringobrigatório
        Alíquota padrão do componente, fração decimal em string, com 6 casas: 0.009000 = 0,9%.
    • componentsarray<um de>obrigatóriopode 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.
      ›2 formas possíveis

      status = STANDARD

      • componentstringobrigatório
        Componente: CBS, IBS_UF ou IBS_MUN. Trate a lista como aberta: novos componentes podem surgir.
        Valores:CBSIBS_UFIBS_MUN
      • cststringobrigatório
        CST do componente. Igual ao da alternativa.
      • cClassTribstringobrigatório
        cClassTrib do componente. Igual ao da alternativa.
      • statusstringobrigató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
      • standardRatestringobrigatório
        Alíquota padrão do componente na data de referência, fração decimal em string, com 6 casas.
      • reductionPctstringobrigatório
        Redução aplicada ao componente, fração decimal em string, com 6 casas.
      • effectiveRatestringobrigatório
        Alíquota efetiva: standardRate × (1 − reductionPct), fração decimal em string, com 6 casas.

      status = NOT_DUE

      • componentstringobrigatório
        Componente: CBS, IBS_UF ou IBS_MUN. Trate a lista como aberta: novos componentes podem surgir.
        Valores:CBSIBS_UFIBS_MUN
      • cststringobrigatório
        CST do componente. Igual ao da alternativa.
      • cClassTribstringobrigatório
        cClassTrib do componente. Igual ao da alternativa.
      • statusstringobrigató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
    • calculationum deobrigatório
      Estado do cálculo da alternativa. Uma alternativa sem cálculo continua na resposta, com o motivo.
      ›3 formas possíveis

      status = CALCULATED

      • statusstringobrigatório
        CALCULATED (componentes STANDARD), NOT_DUE (componentes NOT_DUE) ou UNAVAILABLE (components nulo).
        Valores:CALCULATED

      status = NOT_DUE

      • statusstringobrigatório
        CALCULATED (componentes STANDARD), NOT_DUE (componentes NOT_DUE) ou UNAVAILABLE (components nulo).
        Valores:NOT_DUE

      status = UNAVAILABLE

      • statusstringobrigatório
        CALCULATED (componentes STANDARD), NOT_DUE (componentes NOT_DUE) ou UNAVAILABLE (components nulo).
        Valores:UNAVAILABLE
      • reasonstringobrigatório
        Só em UNAVAILABLE: TAX_CLASSIFICATION_MISSING, CST_MISMATCH, RATE_MISSING ou CALCULATION_UNSUPPORTED.
        Valores:TAX_CLASSIFICATION_MISSINGCST_MISMATCHRATE_MISSINGCALCULATION_UNSUPPORTED
Exemplo · 200
{
"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.›
Exemplo · 400
{
"error": "INVALID_REQUEST"
}
401Chave ausente, malformada, inexistente, revogada ou de cliente desativado. Não consome franquia.›
Exemplo · 401
{
"error": "INVALID_API_KEY"
}
429Franquia mensal esgotada. As consultas voltam a ser aceitas na virada do mês (horário de Brasília).›
Exemplo · 429
{
"error": "QUOTA_EXCEEDED"
}
500Erro inesperado. Repita com backoff exponencial.›
Exemplo · 500
{
"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ório
    Código do erro, sem mensagem detalhada. Ver Erros e novas tentativas.
    Valores:SERVICE_UNAVAILABLE
Exemplo · 503
{
"error": "SERVICE_UNAVAILABLE"
}

Testar

A chamada sai do seu navegador direto para a API, com a sua chave. É uma chamada real: o que consome franquia numa integração consome aqui também.

Fica só nesta aba (sessionStorage) e vai apenas no cabeçalho Authorization.

POST https://app-web-hmg-01-api-gettax-hmg-dvawffg9g9cpcef3.brazilsouth-01.azurewebsites.net/v1/classifications/resolve