> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquerapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Conceitos fundamentais da API Liquerapay v1.

A API Liquerapay segue um conjunto pequeno de **convenções** que se repetem
em todos os endpoints. Conhecê-las economiza tempo e evita surpresas.

## Princípios

* **REST**: cada recurso tem uma URL e usa verbos HTTP (`GET`, `POST`, `PATCH`, `DELETE`).
* **JSON**: requisições e respostas são JSON com `Content-Type: application/json`.
* **Centavos**: todos os valores monetários são **inteiros em centavos**. Nunca use float.
* **Cursor pagination**: listas usam paginação bidirecional por cursor (`after`/`before` + `limit`).

## Envelope de resposta

Toda resposta segue o padrão `{ data, error, success }`.

<CodeGroup>
  ```json Sucesso (item único) theme={null}
  {
    "data": {
      "id": "cust_018f3a2b7c4d7c40a1b2",
      "name": "João Silva"
    },
    "error": null,
    "success": true
  }
  ```

  ```json Sucesso (lista paginada) theme={null}
  {
    "data": [
      { "id": "chg_018f8e2d9a5f7b10c3d4", "amount": 5000, "status": "PAID" },
      { "id": "chg_018f8e2e0a1b7c20d3e4", "amount": 1500, "status": "PENDING" }
    ],
    "pagination": {
      "hasMore": true,
      "next": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTE5In0",
      "before": null
    },
    "error": null,
    "success": true
  }
  ```

  ```json Erro theme={null}
  {
    "error": "VALIDATION_ERROR",
    "message": "amount: deve ser um número inteiro positivo",
    "success": false
  }
  ```
</CodeGroup>

## Códigos HTTP

| Código | Quando acontece                                 |
| ------ | ----------------------------------------------- |
| `200`  | Sucesso (`GET`, `PATCH`, `DELETE`)              |
| `201`  | Recurso criado com sucesso (`POST`)             |
| `400`  | Validação ou regra de negócio violada           |
| `401`  | Token inválido ou ausente                       |
| `403`  | Operação não permitida (ex.: saques bloqueados) |
| `404`  | Recurso não encontrado                          |
| `409`  | Conflito (ex.: documento duplicado)             |
| `429`  | Rate limit excedido                             |
| `500`  | Erro interno (tente novamente)                  |

## Códigos de erro mais comuns

| `error`            | Significado                                        |
| ------------------ | -------------------------------------------------- |
| `VALIDATION_ERROR` | Falha de validação no body / query params          |
| `UNAUTHORIZED`     | Token inválido, ausente ou revogado                |
| `FORBIDDEN`        | Operação não permitida para este merchant          |
| `NOT_FOUND`        | Recurso solicitado não existe                      |
| `CONFLICT`         | Duplicidade detectada                              |
| `BAD_REQUEST`      | Regra de negócio violada (ex.: saldo insuficiente) |
| `RATE_LIMITED`     | Excedeu o limite de requisições                    |
| `INTERNAL_ERROR`   | Erro inesperado no servidor                        |

## Paginação

Listas são paginadas por **cursor bidirecional**, não por offset. Para buscar
a próxima página:

1. Faça `GET /transparents/list?limit=20`
2. Pegue o `pagination.next` da resposta
3. Faça `GET /transparents/list?limit=20&after={next}`
4. Repita até `pagination.hasMore === false`

```bash theme={null}
curl "https://api.liquerapay.com/transparents/list?limit=50" \
  -H "Authorization: Bearer $LIQUERAPAY_API_KEY"
```

<Tip>
  `limit` aceita valores entre **1 e 100** (padrão: 20). Use `before` (em vez
  de `after`) para navegar para a página anterior.
</Tip>