Autenticação

A API do lojista é autenticada por um par de chaves: um identificador público (pk_…) e um token secreto (sk_…). Os dois viajam em headers próprios, em toda requisição.

O par de chaves

Chave	Header	Prefixo	Onde pode aparecer
API key	x-api-key	pk_	Identifica a sua loja. Não é secreta por si só.
Token	x-token	sk_	Segredo. Só no seu servidor.

A Avexus guarda apenas o hash SHA-256 do token — ele nunca é gravado em claro e nunca volta a ser exibido. A comparação na autenticação é feita em tempo constante.

O sk_ nunca sai do servidor

Um sk_ exposto no navegador, no app ou num repositório dá a quem o encontrar o poder de criar cobranças e solicitar saques na sua conta. Se isso acontecer, rotacione as chaves imediatamente.

Gerar e rotacionar

1. Gere o par no painel, em Integração → Chaves de API.

   O sk_ aparece uma única vez, no momento da criação. Guarde-o no seu cofre de segredos na hora.

2. Use o par nos headers de toda requisição (veja abaixo).

3. Rotacione quando precisar — em Integração → Rotacionar chaves.

   A rotação emite um par novo e revoga todos os pares anteriores da conta. Não existe janela de convivência: troque a credencial na sua aplicação junto com a rotação.

Headers

Obrigatórios:

Header	Quando	Descrição
x-api-key	Sempre	A sua API key (pk_…).
x-token	Sempre	O seu token (sk_…).
Content-Type	Requisições com corpo	Sempre application/json.
idempotency-key	Todo POST	Chave única por operação — veja abaixo.

Opcional:

Header	Descrição
x-timezone	Fuso dos campos de data/hora da resposta (ex.: America/Sao_Paulo). Padrão: UTC.

Faltando x-api-key ou x-token, a resposta é 401 com Missing x-api-key or x-token header. Se o par não confere, a resposta é 401 com Invalid API credentials — a mesma mensagem para chave inválida e token inválido, de propósito: a API não revela qual dos dois falhou.

Requisição autenticada

curl --request GET \
  --url https://api.avexus.app/api/balance \
  --header 'x-api-key: pk_1a2b3c4d5e6f' \
  --header 'x-token: sk_9f8e7d6c5b4a3f2e1d0c9b8a' \
  --header 'x-timezone: America/Sao_Paulo'

Idempotência

Todo POST que move dinheiro (/api/transactions, /api/withdrawals) e o registro de webhook exigem o header idempotency-key. Use um valor único por operação — um UUID por pedido, por exemplo.

O comportamento é exato:

Situação	Resposta
Primeira chamada com a chave	Executa normalmente e guarda a resposta.
Repetição com o mesmo corpo	Devolve a resposta guardada, com o header Idempotency-Replay: true. Nada é executado de novo.
Repetição com corpo diferente	422 idempotency-key already used with a different payload
Duas chamadas simultâneas com a mesma chave	409 A request with this idempotency-key is still being processed
Chave ausente	400 idempotency-key header is required

Erro 5xx pode ser repetido

Respostas 5xx não são guardadas: a chave é liberada e uma nova tentativa com o mesmo idempotency-key executa de fato, em vez de repetir o erro.

Retry seguro após timeout

# A primeira tentativa deu timeout — repita com a MESMA chave.
curl --request POST \
  --url https://api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: pk_1a2b3c4d5e6f' \
  --header 'x-token: sk_9f8e7d6c5b4a3f2e1d0c9b8a' \
  --header 'idempotency-key: 7d3c0a2e-9b41-4f52-8a1c-0d6f2b7e5a31' \
  --data '{
    "amount": 4.00,
    "external_ref": "pedido_1042",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix"
  }'

Escopos

Cada chave carrega um conjunto de escopos que limita o que ela pode fazer — uma chave de leitura não cria cobrança nem saque. A lista está em Escopos de API key.

Limites de requisição

Limite	Valor padrão	Resposta ao estourar
Por IP de origem	120 req/min	429 · Rate limit exceeded for this IP
Por lojista	300 req/min	429 · Rate limit exceeded for this merchant

O limite por IP é aplicado antes da autenticação, para conter tentativa de força bruta em credencial; o limite por lojista, depois. Os valores acima são o padrão da plataforma e podem ser ajustados por conta.

Ambientes e credenciais

As chaves são por ambiente. Um par gerado no sandbox não autentica em produção, e vice-versa. O login do painel é o mesmo nos dois; o que muda é o ambiente selecionado ao gerar as chaves.

Ambiente	URL base	Chaves
Produção (live)	https://api.avexus.app	Geradas com o ambiente Live selecionado
Sandbox (demo)	https://sandbox-api.avexus.app	Geradas com o ambiente Sandbox selecionado

Veja também

• Códigos de erro — o que cada status significa.
• Escopos de API key — o que cada escopo libera.
• Quickstart — a primeira cobrança de ponta a ponta.