Autenticação (API Key)

Toda a API de integração é autenticada por API Key, enviada no header X-Api-Key.

Nota

As API Keys e os endpoints de webhook são criados/gerenciados no painel (autenticado por JWT) — essas telas ficam fora do escopo deste documento, que cobre apenas a integração por API Key.

Enviada no header X-Api-Key com o valor cru da chave (sem prefixo Bearer).

Formato da chave: {prefix}.{type}.{secret} Exemplo: ab12cd34.public.<48-chars-secret>

• prefix — 8 caracteres aleatórios (base64url). Usado para lookup.
• type — public ou secret (lowercase).
• secret — 48 caracteres aleatórios.

Como o servidor valida:

1. Localiza a chave pelos primeiros 8 caracteres (o prefixo).
2. Compara a chave completa com o hash guardado (o segredo cru nunca é armazenado).
3. Verifica expiração, o tipo exigido pela rota, a situação da empresa e os scopes.

Requisição autenticada

curl -X POST https://api.gestaotechnology.com/api/payments/merchant/transaction/pix \
  -H "X-Api-Key: ab12cd34.public.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Erros de autenticação:

Status	Situação
401	Header ausente (Missing API key), chave inválida (Invalid API key), chave expirada (API key expired), tipo errado (API key type must be {TYPE})
403	Empresa BLOCKED ou INACTIVE; scope ausente (API key missing required scope)
400	Body ou parâmetros inválidos