Operação da integração · v1 em prévia

Percorra a coleção pelo cursor retornado.

Use limit para escolher o tamanho da página e next_cursor para continuar.

Parâmetros

Parâmetro	Contrato
limit	Inteiro de 1 a 100. Padrão: 50.
cursor	Valor opaco retornado em next_cursor. Omita na primeira chamada.

Produtos e vendas são ordenados por created_at e id, do mais recente para o mais antigo. Acessos usam granted_at e id. Preserve o cursor exatamente como recebido e codifique-o como parâmetro de URL. Não decodifique nem construa cursores por conta própria.

Quando parar

Fim da coleção

next_cursor: null indica o fim.
A API não usa offset.

Durante a varredura

Mantenha o mesmo recurso do início ao fim.
Avance somente com o cursor da resposta anterior.

Exemplo de leitura por páginas no servidor

O gerador abaixo entrega uma página por vez, preserva o cursor e interrompe a leitura ao final. O teto de páginas é uma proteção local do exemplo, não um limite da API. Ele encerra em erro HTTP ou de rede; aplique a política de retentativas na rotina que o utiliza.

JavaScript

export async function* paginasDeProdutos(base, token) {
  if (!base || !token) throw new Error("Configure o ambiente Akrus");
  let cursor = null;
  const vistos = new Set();
  for (let pagina = 0; pagina < 10000; pagina += 1) {
    const url = new URL("/api/v1/products", base);
    url.searchParams.set("limit", "100");
    if (cursor !== null) url.searchParams.set("cursor", cursor);
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
      cache: "no-store",
      signal: AbortSignal.timeout(10000),
    });
    if (!response.ok) throw new Error(`Akrus HTTP ${response.status}`);
    const body = await response.json();
    if (body.version !== "v1" || !Array.isArray(body.data) ||
        !(body.next_cursor === null || typeof body.next_cursor === "string")) {
      throw new Error("Envelope inesperado");
    }
    if (body.next_cursor !== null) {
      if (!body.next_cursor || vistos.has(body.next_cursor)) {
        throw new Error("Cursor vazio ou repetido");
      }
      vistos.add(body.next_cursor);
    }
    yield body.data;
    if (body.next_cursor === null) return;
    cursor = body.next_cursor;
  }
  throw new Error("Limite local de páginas atingido; revise a sincronização");
}

Persistência e reconciliação

Salve os registros por identificador e prepare a escrita local para reprocessamento. Se a execução parar, registre o ponto de retomada somente após processar a página. Uma leitura paginada não declara um snapshot imutável da coleção; mudanças durante a consulta exigem reconciliação posterior.

Preserve o timestamp original quando precisar dele para auditoria. Não reconstrua cursores a partir de datas convertidas por JavaScript: a precisão original pode incluir microssegundos.

Referência conferida em 23 de setembro de 2026. Relatar uma dúvida na documentação.