Paginación de la API (page, per_page y cursor)

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 en 1.
• per_page: cantidad de ítems por página, máximo 100 (por defecto 15).

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": "..." }
}

Usá links.next directamente para avanzar sin recalcular la URL vos mismo.

Paginación por cursor

Agregá ?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, pasá ?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), preferí cursor: page/per_page con LIMIT/OFFSET se vuelve lento en páginas muy altas.
• Detené el recorrido cuando has_more sea false o next_cursor sea null.

Solución de problemas

• Se repiten o faltan registros al paginar con page: si el listado se ordena por un campo que cambia (como last_message_at), la inserción de nuevas filas puede correr los resultados entre páginas; cambiá a cursor.
• per_page mayor a 100 no tiene efecto: el máximo permitido es 100; valores mayores se recortan.