> ## Documentation Index
> Fetch the complete documentation index at: https://abacatepay-feat-lojista.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={3}>
  <Card title="Autenticação" icon="key" href="/pages/authentication">
    Como gerar e usar suas chaves de API.
  </Card>

  <Card title="Dev mode" icon="code" href="/pages/devmode">
    Testar sem risco antes de ir para produção.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pages/webhooks">
    Receber notificações de eventos em tempo real.
  </Card>
</CardGroup>

***

## 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`:

```bash theme={null}
Authorization: Bearer SUA_CHAVE_API
```

Requisições sem chave ou com chave inválida retornam `401 Unauthorized`. Consulte a [página de autenticação](/pages/authentication) para criar e gerenciar suas chaves.

***

## Formato de resposta

Todos os endpoints retornam JSON com a mesma estrutura:

```json theme={null}
{
  "data": { ... },
  "success": true,
  "error": null
}
```

Em caso de erro:

```json theme={null}
{
  "data": null,
  "success": false,
  "error": "Mensagem descritiva do erro"
}
```

<Info>
  Sempre verifique `success` antes de acessar `data`. Nunca assuma que a requisição funcionou apenas pelo status HTTP.
</Info>

***

## 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](/pages/authentication) 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Dicas gerais

<CardGroup cols={2}>
  <Card title="Use Dev mode para testes" icon="code" href="/pages/devmode">
    Chaves de desenvolvimento simulam pagamentos sem cobranças reais.
  </Card>

  <Card title="Armazene a chave em variável de ambiente" icon="shield">
    Nunca comite sua chave de API no código. Use `process.env`, `.env` ou um gerenciador de segredos.
  </Card>

  <Card title="Idempotência em webhooks" icon="repeat" href="/pages/webhooks">
    Sempre registre o ID do evento recebido e descarte duplicatas.
  </Card>

  <Card title="Backoff em erros 5xx" icon="rotate">
    Implemente retentativas com espera crescente para falhas temporárias.
  </Card>
</CardGroup>