Auth & sandbox

Toda chamada autenticada usa Authorization: Bearer ….

API keys

• Prefixo sk_test_ (sandbox) ou sk_live_
• Dev local: sk_test_aporta_dev
• Gerencie via /v1/api-keys/* ou dashboard (sessão merchant)

Permissões

Chaves gerenciadas podem usar * ou permissões por recurso, como customers:read,customers:write e equivalentes para products, checkouts, payment-links, transparents, coupons, subscriptions, webhooks e payouts. Rotas de leitura exigem :read; criação/alteração exigem :write. A chave sandbox padrão mantém acesso *.

Envelope

{
  "data": { ... },
  "success": true,
  "error": null
}

Merchant session

POST /v1/auth/register · POST /v1/auth/login devolvem sess_… para o dashboard web.

Sandbox

Use */simulate-payment, */simulate-dispute e similares para forçar estados sem provedor real. Valores sempre em centavos BRL. Recursos criados com sk_test_ incluem devMode: true.

Rate limit

Limite in-memory por API key (padrão 120 req / 60s). Excedeu → 429 com Retry-After e headers X-RateLimit-*. Env: RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, RATE_LIMIT_DISABLED=1.

Fees & loja

• GET /v1/fees/calculate?amount=&method= — estimativa sandbox
• GET /v1/stores/list — loja atual (multi-store stub)
• Saque mínimo R$ 3,50 · taxa R$ 0,80 (fee / netAmount)