Paginação

Todos os endpoints de listagem usam paginação baseada em cursor, apenas para frente. Essa abordagem é confiável para grandes volumes de dados e lida bem com inserções concorrentes -- diferente da paginação por offset, você nunca verá registros duplicados ou faltando.

Toda resposta de listagem inclui um array data e um booleano has_more:

{
  "data": [
    { "id": "cust_aaa111", "name": "Alice" },
    { "id": "cust_bbb222", "name": "Bob" },
    { "id": "cust_ccc333", "name": "Carlos" }
  ],
  "has_more": true
}

Quando has_more é true, passe o id do último item como starting_after para buscar a próxima página.

let hasMore = true;
let startingAfter: string | undefined;

while (hasMore) {
  const page = await dinie.customers.list({
    limit: 25,
    starting_after: startingAfter,
  });

  for (const customer of page.data) {
    console.log(customer.id, customer.name);
  }

  hasMore = page.has_more;
  if (page.data.length > 0) {
    startingAfter = page.data[page.data.length - 1].id;
  }
}

{
  "data": [
    { "id": "cust_aaa111", "name": "Alice" },
    { "id": "cust_bbb222", "name": "Bob" }
  ],
  "has_more": true
}

Próxima página -- passe o último ID:

curl "https://sandbox.api.dinie.com.br/v3/customers?limit=2&starting_after=cust_bbb222" \
  -H "Authorization: Bearer dinie_at_..."

{
  "data": [
    { "id": "cust_ccc333", "name": "Carlos" }
  ],
  "has_more": false
}

Os SDKs fornecem iteradores de paginação automática que gerenciam o cursor starting_after para você. Esta é a abordagem recomendada para iterar sobre todos os itens de uma coleção.

for await (const customer of dinie.customers.list({ limit: 100 })) {
  console.log(customer.id, customer.name);
}

Tip: A paginação automática faz requisições sequenciais por baixo dos panos, buscando a próxima página somente quando você consome todos os itens da página atual. Defina limit: 100 para minimizar o número de requisições HTTP.

Alguns endpoints suportam ordenação com os parâmetros sort e order:

curl "https://sandbox.api.dinie.com.br/v3/customers?sort=created_at&order=asc&limit=25" \
  -H "Authorization: Bearer dinie_at_..."

A paginação sempre percorre a ordem de classificação atual. Quando você usa starting_after, a API retorna itens que vêm após o ID especificado na ordem de classificação selecionada.

Uma coleção vazia retorna um array data vazio:

{
  "data": [],
  "has_more": false
}

Info: Endpoints com coleções naturalmente pequenas (webhook endpoints, credenciais de API) ainda usam o envelope padrão { "data": [...], "has_more": false } por consistência.