Paginação

As listas de clientes (GET /public/v1/clients), de endereços (GET /public/v1/clients/{id}/addresses), de tarefas (GET /public/v1/tasks), da agenda (GET /public/v1/appointments), de orçamentos (GET /public/v1/quotes), de ordens de serviço (GET /public/v1/service_orders), de tipos de OS (GET /public/v1/service_order_types) de equipe (GET /public/v1/team), de produtos (GET /public/v1/products), de variações (GET /public/v1/products/{id}/variations), de categorias de produto (GET /public/v1/product_categories), do extrato de estoque (GET /public/v1/stock_movements), de serviços (GET /public/v1/services), de categorias de serviço (GET /public/v1/service_categories), de vendas (GET /public/v1/sales), de versões de uma venda (GET /public/v1/sales/{id}/versions), de lançamentos (GET /public/v1/financial_transactions), de contas (GET /public/v1/financial_accounts) e de categorias do financeiro (GET /public/v1/financial_categories) já seguem tudo o que está nesta página, e as das próximas fases seguem igual. A Referência é a lista do que responde hoje.

Como funciona

Lista longa não sai numa resposta só. A API corta em páginas e devolve, junto com os dados, a marca de onde parou. Você pede a próxima página mandando essa marca de volta.

Duas coisas entram na consulta:

Parâmetro	O que é
`limit`	Quantos registros você quer na página. Padrão 20, máximo 100
`cursor`	A marca de onde continuar. Na primeira chamada, não mande

A resposta tem sempre este formato:

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "Y3JlYXRlZF9hdDoy..."
}

Campo	O que é
`object`	Sempre `"list"`. É como você reconhece uma resposta de lista
`data`	Os registros desta página, na ordem da consulta
`has_more`	`true` quando ainda existe página depois desta
`next_cursor`	A marca para pedir a próxima página

O que o cliente guarda entre páginas

Só o next_cursor. Nada mais.

Não guarde o número da chamada, o total de registros lidos nem o último id visto para tentar continuar por ele. O cursor já carrega tudo o que a API precisa para retomar do lugar certo.

Como saber que acabou

Pare quando has_more for false. Enquanto ele for true, mande o next_cursor de volta no parâmetro cursor e peça de novo.

Não use o tamanho de data como sinal de fim. Uma página pode vir menor que o limit e ainda ter continuação.

O cursor é opaco

O valor do cursor é um texto que só a API entende. Trate como caixa-preta:

Não interprete. Ele parece legível em alguns casos, mas o conteúdo dele é assunto interno e pode mudar sem aviso, porque isso não quebra ninguém que só devolve o valor.
Não construa na mão. Cursor inventado é recusado.
Não mexa. Mande exatamente o texto que veio, sem cortar, sem decodificar, sem trocar caractere.

Por que não existe número de página

Com número de página, a página 2 quer dizer “pule os 20 primeiros”. Se alguém criar um registro entre a sua chamada da página 1 e a da página 2, tudo desce uma posição: o vigésimo registro da página 1 vira o primeiro da página 2, e você o lê duas vezes. Se alguém apagar um registro, acontece o contrário e um registro nunca aparece.

O cursor não conta posição, ele marca um ponto na ordenação. Registro criado depois da sua primeira página não empurra nada, e a varredura termina sem repetir nem pular.

É por isso também que não existe offset nem page na API.

Filtros e ordem

Toda lista aceita os mesmos três filtros de data:

Filtro	O que faz
`created_after`	Só o que foi criado depois deste instante
`created_before`	Só o que foi criado antes deste instante
`updated_after`	Só o que mudou depois deste instante

A ordem padrão é created_at decrescente, do mais novo para o mais antigo.

Com updated_after, a ordem vira updated_at crescente. Esse é o modo de sincronização: você guarda o maior updated_at que viu, e na próxima rodada continua dali, sem reler o que não mudou. As datas seguem o formato de Datas e dinheiro.

Não existe ordenação livre nem filtro por campo qualquer. Cada recurso declara os filtros próprios dele na Referência.

Próximo passo

Datas e dinheiro: o formato das datas que os filtros aceitam.
Limites de uso: varredura de lista longa gasta orçamento de chamadas.