Paginación

Navega eficientemente por grandes volúmenes de datos usando cursores offset.

¿Por qué paginamos?

Endpoints que devuelven colecciones de objetos, como listar todos tus clientes o cotizaciones, pueden devolver cientos de miles de registros. Para asegurar que la API de Cord sea siempre rápida y estable, estos endpoints limitan la cantidad de objetos devueltos por defecto (generalmente 50 o 100) utilizando un modelo de paginación basado en limit y offset.

Parámetros de Consulta

Todas las rutas de lectura de listas (GET /api/v1/cotizaciones, GET /api/v1/clientes, GET /api/v1/productos) aceptan los siguientes parámetros en la URL:

limit: (Entero) Determina el número máximo de resultados a devolver.
offset: (Entero) Especifica cuántos resultados saltar antes de comenzar a devolver los datos.

Ejemplo de Petición (Página 2):

curl -X GET "https://cordhq.app/api/v1/clientes?limit=50&offset=50" \
     -H "Authorization: Bearer sk_live_tU..."

Estructura de Respuesta (Meta)

Todas las respuestas paginadas de Cord devuelven un objeto JSON con dos propiedades principales: data (el arreglo de objetos) y meta (información sobre la paginación para tu frontend o scripts).

{
  "data": [
    { "id": "cus_123", "empresa": "ACME Corp" },
    { "id": "cus_124", "empresa": "Stark Ind" }
  ],
  "meta": {
    "limit": 50,
    "offset": 50,
    "total": 142
  }
}

Usa meta.total para construir controles de paginación en tu interfaz de usuario o para saber exactamente cuándo detener un script de exportación de datos.

Excepciones: facturas y eventos usan cursor, no offset

Las facturas se listan con keyset pagination (cursor / next_cursor), no con limit/offset. Con offset, una factura nueva desplaza toda la página siguiente y puede esconder un registro sin que te enteres — algo inaceptable en un listado que alimenta cobranza o conciliación contable.

curl -X GET "https://cordhq.app/api/v1/facturas?limit=50" \
     -H "Authorization: Bearer sk_live_tU..."

{
  "data": [ { "id": "fac_...", "numero": "F-2026-104", "estado": "open" } ],
  "meta": { "next_cursor": "2026-08-20T14:32:00.000Z" }
}

next_cursor es la fecha de creación (ISO 8601) de la última fila de la página, no un token opaco: repite la petición agregando ?cursor=<next_cursor> para traer la siguiente. Cuando ya no hay más páginas, next_cursor viene null.

GET /api/v1/events también pagina con cursor, pero su next_cursor es un token opaco: no intentes interpretarlo ni construirlo, solo reenvíalo tal cual en ?cursor=. Ver Historial de eventos por API.