Introdução

Base URL, autenticação, formato de resposta, códigos de status e limites da API.

Esta seção documenta os endpoints da API da AbacatePay v2. Todos os recursos seguem as mesmas convenções de autenticação, formato de resposta e tratamento de erros descritas aqui. Leia esta página uma vez — ela evita a maioria dos erros de integração.

Autenticação

Como gerar e usar suas chaves de API.

Dev mode

Testar sem risco antes de ir para produção.

Webhooks

Receber notificações de eventos em tempo real.

---

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ódigo	Significado
200	Sucesso
400	Requisição inválida — verifique os campos enviados
401	Não autenticado — chave ausente, inválida ou revogada
403	Sem permissão — a chave não tem acesso ao recurso solicitado
404	Recurso não encontrado
422	Erro de validação — dados corretos mas semanticamente inválidos
429	Rate limit atingido
5xx	Erro 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.

---

Erros mais comuns

400 — os campos estão corretos mas a requisição é rejeitada

Verifique o tipo dos valores. A API é tipada: amount é sempre inteiro em centavos (1000 = R$ 10,00), não decimal. IDs de produtos e clientes são strings, não números.

401 — chave válida mas ainda recebo Unauthorized

Confirme que o header está exatamente como Authorization: Bearer SUA_CHAVE — com espaço entre Bearer e a chave, sem aspas extras.

403 — tenho a chave mas não tenho acesso ao endpoint

A chave existe mas não tem a permissão necessária. Vá no dashboard → Integração → edite a chave → adicione a permissão do recurso que está tentando acessar.

422 — dados válidos mas semanticamente errados

Exemplo: criar uma assinatura com um produto que não tem cycle definido. Os campos estão corretos individualmente, mas a combinação não faz sentido. A mensagem de erro no campo error da resposta descreve o problema específico.

5xx — erro do servidor

Erros 5xx são temporários. Implemente retentativas com backoff exponencial (ex: aguarde 1s, depois 2s, depois 4s). Se persistir por mais de alguns minutos, entre em contato com o suporte.

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.