Conceitos

Boas práticas

O que guardar, como tratar valores fiscais e como integrar o GetTax a um emissor de documentos fiscais.

Envie a operação real#

• Envie o CFOP da operação que vai ser emitida. Não use um CFOP de venda como padrão para tudo: devolução, transferência e remessa podem ter outro CST.
• Envie sector quando souber o setor do seu cliente final. Sem setor, vêm todas as alternativas, de qualquer setor.
• Valide o dígito verificador do GTIN antes de enviar. Um GTIN inválido não consome franquia, mas custa uma ida e volta.

Trate os quatro status#

• Só CLASSIFIED é resultado concluído. IN_REVIEW pode trazer alternativas calculadas, mas não deve ser emitido automaticamente.
• Sem classificação concluída, não presuma tributação integral nem preencha alíquotas por conta própria.
• Com mais de uma alternativa, a escolha é do emissor, pela condição em applicability. Nunca pela posição na lista.

1const res = await fetch(`${process.env.GETTAX_URL}/v1/classifications/resolve`, {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.GETTAX_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({ gtin: "7891000315507", cfop: "5102", sector: "VAREJO_GERAL" }),
8});
9 
10if (!res.ok) {
11  const { error } = await res.json(); // { "error": "INVALID_REQUEST" }, etc.
12  throw new Error(`GetTax ${res.status}: ${error}`);
13}
14 
15const decision = await res.json();
16 
17switch (decision.status) {
18  case "CLASSIFIED":
19    // Todas as alternativas pertinentes. A ordem não é recomendação:
20    // com mais de uma, o emissor escolhe pela condição em `applicability`.
21    await saveDecision(decision);
22    break;
23  case "IN_REVIEW":
24    // Pode trazer alternativas, mas o resultado não está concluído.
25    await sendToReview(decision);
26    break;
27  case "PENDING":
28    // Produto fora do catálogo. Consulte de novo mais tarde, sem loop.
29    await retryLater(decision.gtin, decision.retryAfterSeconds);
30    break;
31  case "NOT_FOUND":
32    // A GS1 não conhece o GTIN: confira o cadastro do item.
33    await flagInvalidGtin(decision.gtin);
34    break;
35}

Guarde a decisão com o documento#

Junto de cada documento fiscal emitido, guarde:

• decisionVersion: identifica a decisão na trilha de auditoria do GetTax.
• referenceDate, cfop e sector usados na consulta.
• Da alternativa aplicada: cst, cClassTrib, rule.id, rule.version, taxClassification.sourceVersion e os sourceVersion de rates[].
• Os valores de components[] como vieram.

É o que permite explicar depois de onde veio cada número, mesmo que a regra ou a alíquota mude.

decisionVersion é novo a cada consulta, mesmo com a mesma entrada e o mesmo resultado. Ele identifica a consulta, não a classificação: para saber se a classificação mudou, compare cst, cClassTrib, rule.id e rule.version.

Valores fiscais como decimal#

Alíquotas e reduções chegam como strings de fração decimal ("0.009000" = 0,9%). Mantenha a precisão:

• Converta direto para um tipo decimal exato e guarde como decimal ou texto. Nunca passe por float ou double.
• Não converta para percentual inteiro antes de guardar. Se precisar exibir, formate só na tela.
• Recalcule, se quiser conferir, com a fórmula effectiveRate = standardRate × (1 − reductionPct), em decimal.

1using System.Globalization;
2 
3// "0.003600" -> 0.003600m, sem passar por double
4var effectiveRate = decimal.Parse(component.GetProperty("effectiveRate").GetString()!, CultureInfo.InvariantCulture);

1from decimal import Decimal
2 
3effective_rate = Decimal(component["effectiveRate"])  # Decimal('0.003600')

Em JavaScript, Number("0.003600") é ponto flutuante. Mantenha a string ou use uma biblioteca decimal.

Reaproveite as respostas#

A classificação depende de GTIN, CFOP, setor e data de referência, não do seu cliente final. Guarde a resposta no seu banco e reutilize entre os seus clientes:

• Use como chave o GTIN de 14 dígitos, o CFOP e o setor (ou a ausência dele).
• A decisão vale enquanto a data de referência estiver dentro da vigência de tudo o que ela usou: o menor effectiveTo entre a regra, a linha de cClassTrib e as alíquotas. null quer dizer sem término previsto.
• A curadoria publica regras e versões novas. Reconsulte periodicamente, e sempre que a data passar de um effectiveTo.
• Não guarde em cache PENDING nem IN_REVIEW como resultado final.

Escolha a rota certa#

• Consulta unitária para o dia a dia: item novo no cadastro, conferência antes da emissão. Pode buscar na GS1 um produto que ainda não está no catálogo, quando a busca está ativa no ambiente, por isso pode levar alguns segundos a mais nesse caso.
• Lote para carga e revisão de catálogo: até 100 itens por requisição, sem busca na GS1. Itens PENDING do lote podem ser reconsultados depois, pela consulta unitária.
• Lista de setores para validar a chave e checar a saúde da integração, sem consumir franquia.

Integração robusta#

• Chame a API pelo seu backend e guarde a chave num cofre de segredos. Ver Autenticação.
• Configure timeout no seu cliente HTTP e repita só 500 e 503, com backoff. Ver Erros e novas tentativas.
• Trate enums como abertos: novos setores e componentes podem surgir. Leia os setores de GET /v1/enums/sectors.
• Ignore campos que você não conhece na resposta, em vez de falhar.