PT EN

Paginação por cursor

Como as listagens devolvem páginas com limit, after, has_more e next_cursor, e como percorrer todas as páginas sem perder registos.

As listagens da API não usam números de página. Cada resposta traz um lote de registos e, quando há mais, um cursor opaco que aponta para o último registo devolvido. O pedido seguinte envia esse cursor e recebe o lote que vem depois.

Parâmetros do pedido#

Parâmetro Onde Comportamento
limit query Número máximo de registos na página. Sem valor, o servidor usa 20; acima de 100, o servidor reduz para 100 sem devolver erro.
after query O valor de next_cursor da página anterior. Na primeira página, não o envie.

O nome do parâmetro é after em todas as listagens declaradas com PageAfter na especificação OpenAPI. Os filtros próprios de cada recurso (por exemplo status ou q) combinam-se com estes dois; veja Filtrar e pesquisar.

Campos da resposta#

Campo Tipo Significado
data array Os registos desta página.
has_more boolean true quando existem registos depois do último de data.
next_cursor string Presente apenas quando has_more é true. Passe-o em after.

Na listagem de clientes, a ordem é do mais recente para o mais antigo, por data de criação e, em caso de empate, por identificador. Como o cursor guarda a posição do último registo e não um número de página, um cliente criado enquanto percorre a lista fica antes do ponto onde está e não aparece duas vezes nem empurra registos para a página seguinte.

Exemplo de pedido e resposta#

bash
curl -sS "$BUSINESS_API/customers?limit=2" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "data": [
    {
      "id": "cus_2kFq8VmZ3xNcR7tLpW4hYb9sDeA",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Amélia Cossa",
      "phone": "+258841234567",
      "status": "active",
      "created_at": "2026-11-19T09:05:12.481203Z",
      "updated_at": "2026-11-19T09:05:12.481203Z"
    },
    {
      "id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "business",
      "category": "institutional",
      "display_name": "Escola Primária de Malhangalene",
      "status": "active",
      "created_at": "2026-11-19T08:20:00.123456789Z",
      "updated_at": "2026-11-19T08:20:00.123456789Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5"
}

Para a página seguinte, repita o pedido com after=Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5. Trate o cursor como texto opaco: não o descodifique nem o construa à mão.

Percorrer todas as páginas#

let after = "";
let customers = [];
do {
  const url = new URL("$BUSINESS_API/customers");
  url.searchParams.set("limit", "100");
  if (after) url.searchParams.set("after", after);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
  if (res.status >= 400) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  customers = customers.concat(page.data);
  after = page.has_more ? page.next_cursor : "";
} while (after);

Na linha de comandos, gotactl customers list --all segue as páginas por si, e gotactl api GET business:/customers --paginate faz o mesmo para qualquer listagem.

Erros de paginação#

Um cursor que o servidor não consegue descodificar, normalmente por ter sido alterado ou copiado de forma incompleta, é recusado com 400 e error_code: "request.cursor_invalid"; recomece a partir da primeira página. Nas listagens de clientes, um limit que não seja um número inteiro não negativo também devolve 400, com error_code: "request.invalid"; corrija o valor e repita o pedido. O formato completo dos erros está em Erros.

Próximos passos#