Paginação e filtros

Existem dois estilos, de propósito. Qual deles um endpoint usa fica visível na resposta dele.

Cursor — para o que cresce pela ponta

Logs de entrega, histórico de sincronização de integração, conversas, mensagens. Essas listas ganham linhas na ponta mais nova o tempo todo, então um deslocamento numérico se move debaixo de você entre uma página e a seguinte: você veria uma linha duas vezes e perderia outra inteira.

bash

curl "https://api.zapyflow.com.br/api/integrations/sync-jobs?limit=50" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

json

{
  "jobs": [ ... ],
  "nextCursor": "cmt1naffo00113tuykpbzlvm9"
}

Devolva o valor em ?cursor=. Cursor null significa que você chegou ao fim. Não monte cursor por conta própria — trate como opaco.

Número de página — para coleções pequenas e estáveis

Contatos, pedidos, itens de catálogo. São navegados por uma pessoa, que espera que “página 3” queira dizer a mesma coisa duas vezes, e a taxa de escrita é baixa o bastante para o deslize não ser problema prático.

bash

curl "https://api.zapyflow.com.br/api/contacts?page=2&limit=50" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

O limit tem teto de 100 em todo lugar. Pedir mais é aparado, não recusado — mas não construa em cima do aparo; peça o que você quer.

Filtros

Filtros são parâmetros de query comuns, com vocabulário fixo (status, from, to, search). Não existe linguagem de expressão de filtro, e não vai existir: uma gramática que ninguém lê é fonte permanente de bug de parsing dos dois lados.

Datas são ISO-8601. Onde um filtro significa “um dia”, o dia é resolvido no fuso do workspace, não em UTC — um pedido feito às 21h em São Paulo pertence àquele dia, não ao seguinte.