Paginacao com cursor na API

Quando usar cursor

Use cursor quando a lista for consumida em múltiplas páginas e você precisa manter consistência entre chamadas sem carregar todo o resultado de uma vez.

Exemplo de loop

let cursor: string | null = null;

do {
  const res = await fetch("https://api.orbioapi.com.br/v1/accounts/search", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ORBIO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      spec,
      limit: 100,
      cursor,
    }),
  });

  const data = await res.json();
  processPage(data.accounts);
  cursor = data.next_cursor ?? null;
} while (cursor);

Boas práticas

• Grave o último cursor processado com sucesso.
• Fixe o snapshot do mês para leituras reprodutíveis.
• Separe tratamento de erro de controle de fluxo.
• Para volumes muito altos, prefira export assíncrono.

Erros comuns

• Recomeçar do zero após falha e duplicar registros.
• Misturar paginação e filtros mutáveis na mesma execução.
• Ignorar o snapshot retornado e perder rastreabilidade.