Paginação da API (page, per_page e cursor)

Os endpoints que retornam listas (contatos, conversas, oportunidades, itens de quadro etc.) usam paginação para não trazer milhares de registros em uma única resposta. O Omnifox suporta dois estilos: paginação por página (padrão) e paginação por cursor.

Paginação por página (padrão)

Parâmetros:

• page: número da página, começando em 1.
• per_page: itens por página, máximo 100 (padrão 15).

A resposta traz:

{
  "success": true,
  "data": [ ... ],
  "meta": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 73, "from": 1, "to": 15 },
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." }
}

Use links.next diretamente para avançar sem montar a URL você mesmo.

Paginação por cursor

Adicione ?pagination=cursor à listagem. A forma da resposta muda:

{
  "items": [ ... ],
  "pagination": {
    "next_cursor": 12345,
    "previous_cursor": 12380,
    "has_more": true,
    "limit": 20
  }
}

Para pedir a próxima página, passe ?cursorId=12345 na chamada seguinte. É o modo recomendado para listas que mudam constantemente (por exemplo, mensagens de uma conversa ativa), porque não "pula" nem repete registros quando novas linhas são inseridas entre uma página e outra.

Exemplo: percorrer todos os contatos com cursor

curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50" \
  -H "Authorization: Bearer SEU_TOKEN"

# próxima página:
curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50&cursorId=12345" \
  -H "Authorization: Bearer SEU_TOKEN"

Dicas

• Para exportações em massa (milhares de registros), prefira cursor: page/per_page usa LIMIT/OFFSET por baixo dos panos, que fica lento em páginas muito altas.
• Pare de percorrer quando has_more for false ou next_cursor for null.

Solução de problemas

• Registros se repetem ou somem ao paginar com page: se a lista é ordenada por um campo que muda (como last_message_at), a inserção de novas linhas pode deslocar os resultados entre páginas; troque para cursor.
• per_page acima de 100 não tem efeito: o máximo permitido é 100; valores maiores são limitados automaticamente.