Paginação

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.

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:

{
  "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).

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.

Paginação por cursor

Disponível nos endpoints de alto volume (por exemplo, listagem de pedidos). É 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).

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.

{
  "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:

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.

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.

Documentação da API

Endpoints de aplicação

Storefront API (Public)

Paginação por página

Paginação por cursor

​Paginação por página

​Paginação por cursor

Paginação por página

Paginação por cursor