Começando

Autenticação

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

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

Formato da chave#

http

1gtx_<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

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

Terminal

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

Quando a autenticação falha#

A resposta é sempre HTTP 401 com o mesmo corpo:

json

1{ "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, 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.

Nota

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:

Crie uma chave nova no portal.
Troque a chave na integração e confirme que ela autentica, com a lista de setores, que não consome franquia.
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

1PDV / ERP  ──▶  seu backend  ──▶  GetTax
2                (guarda a chave)
3 
4navegador  ──✕──▶  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.