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

# Paginação

> Como percorrer listas grandes de clientes, faturas e outros recursos sem perder dados.

Endpoints de listagem (`GET /customers`, `GET /invoices`, etc.) retornam **uma página por vez** usando paginação por cursor (keyset). Você não pula para uma página específica — você avança página por página, do início ao fim.

## Parâmetros

| Parâmetro | Padrão                        | Máximo | Descrição                                                          |
| --------- | ----------------------------- | ------ | ------------------------------------------------------------------ |
| `limit`   | varia por endpoint (10 ou 20) | `100`  | Quantos itens por página                                           |
| `page`    | —                             | —      | **Cursor** opaco da próxima página (recebido na resposta anterior) |

O default exato de cada endpoint está documentado na [referência](/api-reference/introducao). Independente do default, o máximo é sempre **100** itens por página.

<Note>
  `page` aqui **não é um número de página**. É um cursor opaco que o Simplo devolve para você usar na próxima chamada. Não tente construir o cursor manualmente.
</Note>

## Estrutura da resposta

```json theme={null}
{
  "object": "list",
  "url": "/api/v1/customers",
  "has_more": true,
  "data": [
    { "id": "cus_...", "name": "Maria Silva", "...": "..." },
    { "id": "cus_...", "name": "João Santos", "...": "..." }
  ]
}
```

* `object` — sempre `"list"` em respostas de listagem.
* `url` — caminho do endpoint que gerou esta lista.
* `has_more` — `true` se ainda há mais itens depois desta página, `false` se chegou ao fim.
* `data` — os recursos da página atual.

## Próxima página

O cursor para a próxima página vem nos **headers** da resposta. Procure pelos headers padrão de paginação (`Link`, `Current-Page`, `Page-Items`, `Total-Count`) — o cursor para a próxima página é o valor de `page` na URL `rel="next"` do header `Link`.

Exemplo de header:

```http theme={null}
Link: <https://besimplo.com/api/v1/customers?page=eyJpZCI6...&limit=10>; rel="next"
```

Você usa esse cursor diretamente na próxima requisição:

```bash theme={null}
curl "https://besimplo.com/api/v1/customers?page=eyJpZCI6...&limit=10" \
  -H "Authorization: ApiKey $SIMPLO_API_KEY"
```

## Percorrer todas as páginas

```ruby theme={null}
# Ruby
def each_customer(api_key:)
  url = "https://besimplo.com/api/v1/customers?limit=100"
  loop do
    response = HTTP.headers("Authorization" => "ApiKey #{api_key}").get(url)
    body = JSON.parse(response.body.to_s)
    body["data"].each { |customer| yield customer }
    break unless body["has_more"]
    next_link = response.headers["Link"]
    url = next_link[/<([^>]+)>;\s*rel="next"/, 1]
  end
end
```

```javascript theme={null}
// Node.js
async function* allCustomers(apiKey) {
  let url = "https://besimplo.com/api/v1/customers?limit=100";
  while (url) {
    const res = await fetch(url, { headers: { Authorization: `ApiKey ${apiKey}` } });
    const body = await res.json();
    for (const customer of body.data) yield customer;
    if (!body.has_more) break;
    const link = res.headers.get("link") ?? "";
    const match = link.match(/<([^>]+)>;\s*rel="next"/);
    url = match ? match[1] : null;
  }
}
```

<Tip>
  Use `limit=100` (o máximo) para reduzir o número de chamadas e evitar [rate limit](/conceitos/erros#rate-limit-429).
</Tip>

## Filtros

Vários endpoints aceitam filtros adicionais. Por exemplo, listar faturas pagas de um cliente:

```bash theme={null}
curl "https://besimplo.com/api/v1/invoices?customer=cus_xxx&status=paid&limit=100" \
  -H "Authorization: ApiKey $SIMPLO_API_KEY"
```

Os filtros disponíveis estão documentados em cada endpoint na [referência da API](/api-reference/introducao).