# Início rápido

Valide a sua chave e faça a primeira consulta de classificação fiscal.

Versão HTML: https://kind-coast-062131010.2.azurestaticapps.net/guias/inicio-rapido/

O GetTax recebe o GTIN de um produto e o CFOP da operação e devolve as alternativas de enquadramento de CBS e IBS: CST, cClassTrib, alíquotas por componente e fundamento legal, com a versão de cada regra e tabela usada na decisão.

> [!WARNING]
> A API está em homologação. Regras, tabela de cClassTrib e alíquotas ainda estão em validação pela curadoria fiscal e podem incluir dados de demonstração. Não emita documento fiscal real com base nestas respostas.

## Antes de começar

Você precisa de:

- Uma chave de API, no formato `gtx_<16 hex>.<64 hex>`, criada no [portal da revenda](https://app-web-05-prd-wl-gettax-prd.azurewebsites.net), em **Chaves de API**. O acesso ao portal é por convite da equipe GetTax. Ver [Autenticação](https://kind-coast-062131010.2.azurestaticapps.net/guias/autenticacao.md#como-obter-a-chave).
- A URL base da API, informada pela equipe GetTax.
- Um backend para fazer as chamadas. A chave não pode ir para navegador, app ou PDV.

Defina as duas variáveis usadas em todos os exemplos:

```shell
export GETTAX_URL="https://..."   # URL base informada pela equipe GetTax
export GETTAX_KEY="gtx_0123456789abcdef.<segredo de 64 caracteres hexadecimais>"
```

Requisições e respostas usam JSON em UTF-8. Envie `Content-Type: application/json` em toda requisição com corpo.

## 1. Valide a chave

A lista de setores exige chave e não consome franquia. É o jeito mais barato de confirmar que a chave e o cabeçalho estão certos.

```shell
curl -sS "$GETTAX_URL/v1/enums/sectors" \
  -H "Authorization: Bearer $GETTAX_KEY"
```

```json
{
  "sectors": ["VAREJO_GERAL", "BAR_RESTAURANTE", "PRODUTOR_RURAL", "GOVERNO", "ATACADO", "ZONA_FRANCA"]
}
```

Se vier `401` com `{"error": "INVALID_API_KEY"}`, confira a chave e o cabeçalho `Authorization`.

## 2. Consulte um produto

Envie o GTIN e o CFOP da operação. Esta consulta consome uma unidade da [franquia](https://kind-coast-062131010.2.azurestaticapps.net/guias/franquia.md).

```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"}'
```

`sector` (setor do cliente final) e `referenceDate` (data de vigência) são opcionais. Ver [Dados da consulta](https://kind-coast-062131010.2.azurestaticapps.net/guias/dados-da-consulta.md).

## 3. Leia a resposta

Uma resposta `CLASSIFIED` com uma alternativa (valores ilustrativos):

```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" }
    }
  ]
}
```

Leia nesta ordem:

1. **`status`**: `CLASSIFIED` quer dizer que todas as alternativas têm resultado. `PENDING`, `IN_REVIEW` e `NOT_FOUND` também chegam com HTTP 200 e pedem outra ação. Ver [Status e alternativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md).
2. **`classifications[]`**: cada item é uma alternativa de enquadramento. `cst` e `cClassTrib` vão no documento fiscal; `applicability` diz quando a alternativa se aplica. Com mais de uma alternativa, a ordem não é recomendação.
3. **`components[]`**: a alíquota de cada componente. Aqui, CST 200 com redução de 60% (`0.600000`) sobre CBS de 0,9% dá CBS efetiva de 0,36% (`0.003600`). Os valores são strings de fração decimal. Ver [Componentes e alíquotas](https://kind-coast-062131010.2.azurestaticapps.net/guias/componentes-e-aliquotas.md).
4. **`decisionVersion`**: identifica esta decisão na trilha de auditoria. Guarde junto do documento emitido.

## Próximos passos

- [Autenticação](https://kind-coast-062131010.2.azurestaticapps.net/guias/autenticacao.md): formato da chave, troca, revogação e como guardá-la.
- [Status e alternativas](https://kind-coast-062131010.2.azurestaticapps.net/guias/status-e-alternativas.md): o que fazer em cada status.
- [Consultar em lote](https://kind-coast-062131010.2.azurestaticapps.net/referencia/resolve-classification-batch.md): até 100 itens por requisição, para carga de catálogo.
- [Boas práticas](https://kind-coast-062131010.2.azurestaticapps.net/guias/boas-praticas.md): o que guardar, como tratar decimais e quando repetir uma consulta.