Navegue por grandes conjuntos de dados usando paginação baseada em cursor.
A API da AWSales usa paginação baseada em cursor para endpoints que retornam listas de recursos. A paginação por cursor fornece resultados estáveis e consistentes mesmo quando dados estão sendo adicionados ou removidos entre requests.
Em vez de números de página, cursores atuam como ponteiros para uma posição específica no conjunto de resultados. Cada response paginada inclui metadados com cursores que você pode usar para buscar a próxima página ou a anterior.
Cursor para passar como nextCursor para buscar a próxima página
meta.previousCursor
string
Cursor para passar como previousCursor para buscar a página anterior
meta.limit
integer
Número de resultados por página
Alguns endpoints (como Listar Planos) usam paginação baseada em offset com page, limit, totalItems e totalPages em vez de cursores. Consulte a referência do endpoint para o modelo de paginação específico utilizado.
Um loop completo que busca todas as páginas até não haver mais resultados.
async function fetchAllInvoices(orgId, token) { const BASE_URL = "https://api.awsales.io/studio"; const allInvoices = []; let cursor = null; let hasMore = true; while (hasMore) { const url = new URL(`${BASE_URL}/organizations/${orgId}/invoices`); url.searchParams.set("limit", "50"); if (cursor) { url.searchParams.set("nextCursor", cursor); } const response = await fetch(url.toString(), { headers: { Authorization: `Bearer ${token}` }, }); if (!response.ok) { throw new Error(`API error: ${response.status}`); } const { data, meta } = await response.json(); allInvoices.push(...data); hasMore = meta.hasMore; cursor = meta.nextCursor; } return allInvoices;}// Usageconst invoices = await fetchAllInvoices( "019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2", "eyJhbGciOiJSUzI1NiIs...");console.log(`Fetched ${invoices.length} invoices`);
Use o maior valor de limit razoável para reduzir o número de chamadas à API. Menos requests significa menor latência e menos chance de atingir os limites de requisição.
Muitos endpoints suportam filtros via parâmetros de query. Os filtros são aplicados antes da paginação, então os valores de cursor e hasMore refletem o conjunto de resultados filtrado.
# Only PAID invoices, sorted by creation datecurl "https://api.awsales.io/studio/organizations/{orgId}/invoices?status=PAID&sort=createdAt:desc&limit=10" \ -H "Authorization: Bearer ..."
Ao combinar filtros com paginação, use os mesmos parâmetros de filtro em todas as requests de página. Alterar os filtros entre páginas produzirá resultados inconsistentes.
