Paginación de la API (page, per_page y cursor)
Cómo paginar listados de la API de Omnifox con page/per_page o con paginación por cursor.
Mira este paso en el video · Paginación y límites
Los endpoints que devuelven listas (contactos, conversaciones, oportunidades, ítems de tablero, etc.) usan paginación para no traer miles de registros en una sola respuesta. Omnifox soporta dos estilos: paginación por página (por defecto) y paginación por cursor.
Paginación por página (por defecto)
Parámetros:
page: número de página, empieza en1.per_page: cantidad de ítems por página, máximo100(por defecto15).
La respuesta trae:
{
"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": "..." }
}
Usa links.next directamente para avanzar sin recalcular la URL tú mismo.
Paginación por cursor
Agrega ?pagination=cursor al listado. La respuesta cambia de forma:
{
"items": [ ... ],
"pagination": {
"next_cursor": 12345,
"previous_cursor": 12380,
"has_more": true,
"limit": 20
}
}
Para pedir la siguiente página, pasa ?cursorId=12345 en la próxima llamada. Es el modo recomendado para listas que cambian constantemente (por ejemplo, mensajes de una conversación activa), porque no se "salta" ni repite registros cuando se insertan filas nuevas entre una página y otra.
Ejemplo: recorrer todos los contactos con cursor
curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50" \
-H "Authorization: Bearer TU_TOKEN"
# siguiente página:
curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50&cursorId=12345" \
-H "Authorization: Bearer TU_TOKEN"
Consejos
- Para exportaciones masivas (miles de registros), prefiere cursor:
page/per_pageconLIMIT/OFFSETse vuelve lento en páginas muy altas. - Detén el recorrido cuando
has_moreseafalseonext_cursorseanull.
Solución de problemas
- Se repiten o faltan registros al paginar con
page: si el listado se ordena por un campo que cambia (comolast_message_at), la inserción de nuevas filas puede correr los resultados entre páginas; cambia a cursor. per_pagemayor a 100 no tiene efecto: el máximo permitido es 100; valores mayores se recortan.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.