Paginação da API (page, per_page e cursor)
Como paginar listagens da API do Omnifox com page/per_page ou com paginação por cursor.
Veja este passo no vídeo · Paginação e limites
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 em1.per_page: itens por página, máximo100(padrão15).
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_pageusaLIMIT/OFFSETpor baixo dos panos, que fica lento em páginas muito altas. - Pare de percorrer quando
has_moreforfalseounext_cursorfornull.
Solução de problemas
- Registros se repetem ou somem ao paginar com
page: se a lista é ordenada por um campo que muda (comolast_message_at), a inserção de novas linhas pode deslocar os resultados entre páginas; troque para cursor. per_pageacima de 100 não tem efeito: o máximo permitido é 100; valores maiores são limitados automaticamente.
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.