Paginação

As listagens devolvem uma página de cada vez, com um cursor para a seguinte:

{
  "Items": [ ... ],
  "Paging": {
    "Limit": 100,
    "NextCursor": "MTIzNA",
    "HasMore": true
  }
}

Campo	O que é
Items	Os registos desta página
Paging.Limit	O tamanho de página efetivamente aplicado — pode não ser o que pediu
Paging.NextCursor	O que deve enviar para obter a página seguinte. null na última
Paging.HasMore	true se há mais para ler

Percorrer uma listagem

# primeira página
curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/supplier-invoices?limit=100" \
  -H "ApiKey: $GC_API_KEY"

# página seguinte, com o cursor que a anterior devolveu
curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/supplier-invoices?limit=100&cursor=MTIzNA" \
  -H "ApiKey: $GC_API_KEY"

Em JavaScript:

async function readAll(path)
{
    const items = []
    let cursor = null

    do
    {
        const url = new URL(path, base)
        url.searchParams.set('limit', '100')
        if (cursor)
            url.searchParams.set('cursor', cursor)

        const response = await fetch(url, { headers: { ApiKey: key } })
        if (!response.ok)
            throw new Error((await response.json()).Error.Code)

        const page = await response.json()
        items.push(...page.Items)
        cursor = page.Paging.NextCursor
    }
    while (cursor)

    return items
}

Pare pelo cursor, não pelo número de registos

Enquanto NextCursor não for null, há mais. Não deduza o fim de uma página vir com menos registos do que o limit — pode acontecer.

limit

Listagem	Por omissão	Máximo
Condomínios, frações, fornecedores	500	500
Procura de pessoas	50	500
Todas as restantes	100	500

Um limit acima de 500 não dá erro: é reduzido a 500 em silêncio, e o Paging.Limit da resposta diz-lhe o que foi aplicado. Um limit ausente, zero ou negativo usa o valor por omissão.

As listagens cujo total realista cabe numa página — os condomínios de uma empresa, as frações de um condomínio — trazem por omissão o máximo. A paginação continua a existir no contrato, mas na prática raramente precisará dela aí.

O cursor é opaco

Devolva-o exatamente como o recebeu. Não o descodifique, não o construa, não lhe atribua significado e não o guarde como número. É texto seguro para URL, e o que lá está dentro pode mudar.

Um cursor que não tenha sido emitido por esta API responde 400 INVALID_CURSOR — em vez de recomeçar a listagem em silêncio, que o poria num ciclo infinito sem nunca perceber porquê.

Porquê cursor e não número de página

Os registos vão sendo criados enquanto percorre uma listagem. Com números de página, um registo novo empurra os restantes e faz com que salte registos e repita outros. O cursor guarda a posição pelo último registo entregue, e isso não acontece.

O preço é não poder saltar para uma página arbitrária, nem saber o total de antemão: percorre-se para a frente, do princípio ao fim.

Listagens sem paginação

Algumas respostas são um array simples, sem envelope: as apólices e os contratos de manutenção de um condomínio, as tabelas de referência, os destinatários de atribuição, os condóminos de uma fração. São conjuntos pequenos por natureza, e paginá-los seria complicar sem necessidade.

Cada ponto da referência diz qual é o seu caso.