Documentação › Referência › Autenticação

Autenticação

A API Aprovei usa API Keys com Authorization: Bearer e X-Store-Slug em todas as requisições da base https://api.aproveicheckout.com.br/v1.

Como obter sua API Key

  1. Faça login no painel da Aprovei.
  2. No canto superior direito, clique no avatar/menu do usuário.
  3. Acesse API Keys.
  4. Clique em Criar API Key.
  5. Informe um nome para identificar a integração.
  6. Selecione somente as permissões necessárias.
  7. Opcionalmente, restrinja por IP.
  8. Copie a API Key e salve em um local seguro.

Headers

HTTP 
Authorization: Bearer SEU_TOKEN
X-Store-Slug: SLUG_DA_LOJA
Content-Type: application/json

Para operações idempotentes, envie também:

HTTP 
Idempotency-Key: CHAVE_UNICA

Permissões

Permissão Operação permitida
orders:read Consultar pedidos e dados completos de atendimento do cliente. Concessão explícita; o curinga * não basta. Na chave existente, abra Permissões, marque orders:read e salve.
storefront:read Consultar loja, produtos e busca.
checkout:create Criar links de checkout.
pix:create Criar cobranças PIX.
webhooks:read Listar webhooks.
webhooks:create Criar webhooks.

Restrição por IP

Você pode configurar uma allowlist de IPv4 por API Key. Quando configurada, requisições fora da allowlist são bloqueadas com AUTH_IP_NOT_ALLOWED. 

192.168.1.100
10.0.0.50
203.0.113.25

Exemplo

cURL 
curl --location 'https://api.aproveicheckout.com.br/v1/store' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'X-Store-Slug: SLUG_DA_LOJA'

Erros de autenticação

Código Descrição
AUTH_MISSING_BEARER_TOKEN Header Authorization: Bearer ausente.
AUTH_INVALID_BEARER_TOKEN API Key inválida ou revogada.
AUTH_STORE_HEADER_MISSING Header X-Store-Slug ausente.
AUTH_STORE_FORBIDDEN Loja sem vínculo ativo com o dono da key ou permissão insuficiente.
AUTH_IP_NOT_ALLOWED IP fora da allowlist da API Key.

Segurança

Use secrets

Salve a key em variáveis de ambiente, secrets ou cofre de credenciais.

Revogue e rotacione

Revogue keys antigas e gere novas keys quando uma integração mudar de dono ou ambiente.

Nunca exponha no navegador

Use a API Key apenas em backend, server function, edge function privada ou ambiente equivalente.