Skip to main content

​
Base URL

Todas as requisições da v2 usam o seguinte endereço: 
https://api.abacatepay.com/v2
O ambiente (desenvolvimento ou produção) é determinado pela chave de API usada — não pela URL.

​
Autenticação

Toda requisição deve incluir sua chave de API no header Authorization: 
Authorization: Bearer SUA_CHAVE_API
Requisições sem chave ou com chave inválida retornam 401 Unauthorized. Consulte a página de autenticação para criar e gerenciar suas chaves.

​
Formato de resposta

Todos os endpoints retornam JSON com a mesma estrutura: 
{
  "data": { ... },
  "success": true,
  "error": null
}
Em caso de erro: 
{
  "data": null,
  "success": false,
  "error": "Mensagem descritiva do erro"
}
Sempre verifique success antes de acessar data. Nunca assuma que a requisição funcionou apenas pelo status HTTP.

​
Códigos de status HTTP

CódigoSignificado
200Sucesso
400Requisição inválida — verifique os campos enviados
401Não autenticado — chave ausente, inválida ou revogada
403Sem permissão — a chave não tem acesso ao recurso solicitado
404Recurso não encontrado
422Erro de validação — dados corretos mas semanticamente inválidos
429Rate limit atingido
5xxErro interno — tente novamente com backoff exponencial

​
Permissões

Cada chave de API pode ter permissões granulares por recurso. Se você receber 403, verifique se a chave usada tem a permissão necessária para o endpoint. Consulte a página de autenticação para ver todas as permissões disponíveis.

​
Paginação

Endpoints de listagem retornam todos os registros disponíveis. Futuramente suportarão paginação via limit e offset.

​
Dicas gerais

Use Dev mode para testes

Chaves de desenvolvimento simulam pagamentos sem cobranças reais.

Armazene a chave em variável de ambiente

Nunca comite sua chave de API no código. Use process.env, .env ou um gerenciador de segredos.

Idempotência em webhooks

Sempre registre o ID do evento recebido e descarte duplicatas.

Backoff em erros 5xx

Implemente retentativas com espera crescente para falhas temporárias.