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

# Paginação

> Como percorrer listas grandes com cursores estáveis.

Os endpoints de lista usam paginação por cursor. Você navega com o `id` de um item, não com um número de página, então criar ou revogar registros no meio da varredura não desloca o resultado nem faz você pular itens.

Toda página vem ordenada pelo `id`, do maior para o menor. Como os identificadores são ULIDs, isso é a ordem de criação: do mais recente para o mais antigo.

## Endpoints paginados

* [Listar validações](/validacoes/listar)
* [Listar chaves de API](/chaves-de-api/listar)

## Parâmetros

<ParamField query="limit" type="integer" default="20">
  Itens por página, entre 1 e 100. Valores fora dessa faixa são ajustados para o limite mais próximo, sem erro: `limit=500` devolve 100.
</ParamField>

<ParamField query="after" type="string">
  Cursor para avançar. Use o `id` do **último** item da página atual. O item do cursor não volta no resultado.
</ParamField>

<ParamField query="before" type="string">
  Cursor para voltar. Use o `id` do **primeiro** item da página atual. O item do cursor não volta no resultado.
</ParamField>

<Warning>
  Envie um cursor de cada vez. Se os dois vierem na mesma requisição, `before` é aplicado e `after` é ignorado, sem erro.
</Warning>

## Formato da resposta

```json theme={null}
{
  "object": "list",
  "has_more": true,
  "data": []
}
```

<ResponseField name="object" type="string">
  Sempre `list`.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Indica se existem mais itens depois desta página. Use como condição de parada.
</ResponseField>

<ResponseField name="data" type="array">
  Os itens da página, do mais recente para o mais antigo.
</ResponseField>

`has_more` descreve a direção que você pediu: com `after`, indica se há itens mais antigos; com `before`, se há itens mais recentes.

## Avançar página a página

Peça a primeira página, e enquanto `has_more` for `true`, peça a próxima usando o `id` do último item.

<CodeGroup>
  ```bash cURL theme={null}
  # Primeira página
  curl "https://api.id.zapsign.com.br/v1/validations?limit=50" \
    -H "Authorization: Bearer sk_..."

  # Próxima página, a partir do último id da anterior
  curl "https://api.id.zapsign.com.br/v1/validations?limit=50&after=val_0NQW3MVYJYQ453E95V3V1T76AV" \
    -H "Authorization: Bearer sk_..."
  ```

  ```javascript Node.js theme={null}
  const base = "https://api.id.zapsign.com.br/v1";
  const headers = { Authorization: "Bearer sk_..." };

  let after;
  const todas = [];

  do {
    const url = new URL(`${base}/validations`);
    url.searchParams.set("limit", "50");
    if (after) url.searchParams.set("after", after);

    const pagina = await fetch(url, { headers }).then((r) => r.json());
    todas.push(...pagina.data);
    after = pagina.has_more ? pagina.data.at(-1).id : undefined;
  } while (after);
  ```

  ```python Python theme={null}
  import requests

  base = "https://api.id.zapsign.com.br/v1"
  headers = {"Authorization": "Bearer sk_..."}

  after = None
  todas = []

  while True:
      params = {"limit": 50}
      if after:
          params["after"] = after

      pagina = requests.get(f"{base}/validations", headers=headers, params=params).json()
      todas.extend(pagina["data"])

      if not pagina["has_more"]:
          break
      after = pagina["data"][-1]["id"]
  ```
</CodeGroup>

## Voltar

Mesma ideia com `before`, usando o `id` do primeiro item da página atual.

```bash theme={null}
curl "https://api.id.zapsign.com.br/v1/validations?limit=50&before=val_0NQW3MVYJYQ453E95V3V1T76AV" \
  -H "Authorization: Bearer sk_..."
```