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

# Paginação

> Como percorrer listas na API da CentralCart: paginação por página (offset) e por cursor.

Os endpoints de listagem da API da CentralCart paginam os resultados de duas
formas. A maioria usa **paginação por página** (offset). Endpoints de alto volume
(como o de pedidos) também oferecem **paginação por cursor**, mais eficiente para
percorrer bases grandes.

| Modo       | Quando usar                                                | Parâmetros                 |
| ---------- | ---------------------------------------------------------- | -------------------------- |
| Por página | Navegação com números de página, listas pequenas ou médias | `page`, `limit`            |
| Por cursor | Varredura completa, sincronização, bases grandes           | `page_cursor`, `page_size` |

## Paginação por página

Passe `page` (número da página, começa em `1`) e `limit` (itens por página). O
teto e o padrão do `limit` variam por endpoint.

```bash theme={null}
curl "https://api.centralcart.io/v1/app/order?page=2&limit=15" \
  -H "Authorization: Bearer SEU_TOKEN"
```

A resposta traz os itens em `data` e os metadados de paginação em `meta`:

```json theme={null}
{
  "data": [],
  "meta": {
    "total": 320,
    "per_page": 15,
    "current_page": 2,
    "last_page": 22,
    "first_page": 1,
    "first_page_url": "/?page=1",
    "last_page_url": "/?page=22",
    "next_page_url": "/?page=3",
    "previous_page_url": "/?page=1"
  }
}
```

| Campo                                 | Descrição                                                             |
| ------------------------------------- | --------------------------------------------------------------------- |
| `total`                               | Total de itens que casam com o filtro.                                |
| `per_page`                            | Itens por página.                                                     |
| `current_page`                        | Página atual.                                                         |
| `last_page`                           | Última página.                                                        |
| `next_page_url` / `previous_page_url` | Atalho para a próxima e a página anterior (`null` quando não houver). |

<Warning>
  Evite paginação por página em **varreduras completas** de bases grandes. Páginas
  profundas (offset alto) ficam progressivamente mais lentas. Para percorrer tudo,
  prefira o cursor.
</Warning>

## Paginação por cursor

Disponível nos endpoints de alto volume (por exemplo, [listagem de
pedidos](/api-reference/orders/list-order)). É rápida em qualquer profundidade e
não sofre com o custo do offset.

Ative o modo cursor passando `page_cursor`. Use `page_size` para o tamanho da
página (máximo **200**, padrão **50**).

<Note>
  Na primeira chamada envie `page_cursor` vazio (`?page_cursor=`). A resposta traz
  `next_cursor`, que você reenvia em `page_cursor` na chamada seguinte, até
  `next_cursor` vir `null`.
</Note>

```json theme={null}
{
  "data": [],
  "next_cursor": "1b2fe2a9697a0ac07ebd933309b4f9a8d1120c06"
}
```

| Campo         | Descrição                                                                        |
| ------------- | -------------------------------------------------------------------------------- |
| `next_cursor` | Cursor da próxima página. Reenvie em `page_cursor`. Vem `null` na última página. |

Exemplo de varredura completa:

```js theme={null}
let cursor = ""; // vazio = primeira página

do {
  const res = await fetch(
    `https://api.centralcart.io/v1/app/order?page_cursor=${cursor}&page_size=100`,
    { headers: { Authorization: "Bearer SEU_TOKEN" } }
  ).then((r) => r.json());

  for (const pedido of res.data) {
    // processa cada pedido
  }

  cursor = res.next_cursor;
} while (cursor); // para quando next_cursor vier null
```

Os mesmos filtros da listagem (`status`, `from`/`to`, `package`, etc.) funcionam
junto do cursor.

<Tip>
  * Os resultados vêm ordenados por data, do mais recente para o mais antigo.
  * Um `page_size` maior (até 200) reduz o número de chamadas em varreduras
    grandes.
</Tip>