# Autenticação

Envie a chave de API no cabeçalho Authorization, no esquema Bearer, a partir do seu backend.

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

Toda rota em `/v1/` exige uma chave de API, inclusive a lista de setores. Cada software house recebe a sua.

## Formato da chave

```http
gtx_<16 hex>.<64 hex>
```

| Parte | O que é |
| --- | --- |
| `gtx_` + 16 caracteres hexadecimais | Prefixo público. Identifica a chave e pode aparecer em logs. |
| `.` | Separador. |
| 64 caracteres hexadecimais | Segredo. Nunca registre em log nem envie a terceiros. |

## Cabeçalho

Envie a chave inteira, prefixo e segredo, no cabeçalho `Authorization`:

```http
Authorization: Bearer gtx_0123456789abcdef.<segredo de 64 caracteres hexadecimais>
```

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

## Quando a autenticação falha

A resposta é sempre HTTP 401 com o mesmo corpo:

```json
{ "error": "INVALID_API_KEY" }
```

Vale para cabeçalho ausente, fora do formato `Bearer gtx_…`, chave inexistente, chave revogada ou substituída numa rotação e cliente desativado. A API não diz qual foi o caso.

- A autenticação acontece antes da validação do corpo: sem chave válida, a resposta é 401 mesmo que o corpo também esteja errado.
- Requisições recusadas com 401 não consomem franquia.

## Como obter a chave

As chaves são criadas no [portal da revenda](https://app-web-05-prd-wl-gettax-prd.azurewebsites.net), em **Chaves de API**. O acesso ao portal é por convite: quando a equipe GetTax libera a software house, o e-mail de contato recebe o convite. Cada software house é uma organização no portal, e os administradores dela convidam o resto da equipe.

- Crie uma chave por ambiente, com um nome que diga onde ela é usada, por exemplo "Produção" e "Homologação". São até 10 chaves ativas por software house, sem repetir o nome de uma ativa.
- A chave completa aparece **uma única vez**, na criação. Depois, o portal mostra só o prefixo. O GetTax guarda só o hash do segredo: uma chave perdida não pode ser recuperada, só substituída por outra.
- Só administradores da organização criam e revogam chaves. Os demais membros veem a lista, com o último uso de cada chave.
- Todas as chaves da software house dividem a mesma [franquia](https://kind-coast-062131010.2.azurestaticapps.net/guias/franquia.md).

> [!NOTE]
> A chave que a sua integração já usava antes do portal aparece lá como "Chave principal". Ela continua valendo, sem troca.

## Trocar e revogar a chave

Para trocar uma chave sem parada:

1. Crie uma chave nova no portal.
2. Troque a chave na integração e confirme que ela autentica, com a lista de setores, que não consome franquia.
3. Revogue a chave antiga no portal.

As duas chaves valem ao mesmo tempo até a revogação. A revogação vale na hora e não pode ser desfeita: a partir dela, toda chamada com a chave revogada recebe 401.

## Chame a API pelo backend

O PDV, a retaguarda ou o ERP falam com o seu servidor, e o seu servidor fala com o GetTax:

```http
PDV / ERP  ──▶  seu backend  ──▶  GetTax
                (guarda a chave)

navegador  ──✕──▶  GetTax
```

- O CORS da API não libera chamadas feitas direto do navegador. Isso é intencional: protege a chave.
- Guarde a chave num cofre de segredos ou em variável de ambiente do servidor. Nunca em código-fonte, app instalado no cliente ou front-end.
- Se a chave vazar, revogue-a no portal na hora e crie outra.