Paginación

Las colecciones paginan por cursor.

{
  "data": [ … ],
  "meta": { "next_cursor": "eyJpZCI6…", "per_page": 50 }
}

Para traer la siguiente página se manda meta.next_cursor de vuelta como
parámetro de query cursor. next_cursor es null en la última página —
así es como uno sabe que terminó.

GET /units?per_page=50
GET /units?per_page=50&cursor=eyJpZCI6…

El cursor hay que tratarlo como opaco. No es un offset, no es un id, y su
formato no es parte del contrato.

per_page

Por defecto 50. Los valores por encima de 200 se reducen a 200, no se
rechazan — pedir 1000 devuelve 200 y un 200, no un 422.

No hay total ni cantidad de páginas

Deliberadamente. Paginar por offset sobre una tabla que crece no se mantiene
rápido, y un total exige contar filas que nadie va a leer. Ninguna de las dos
cifras está disponible, en ninguna colección.

Si uno está construyendo una interfaz encima de esto, conviene hacer "cargar
más" en vez de páginas numeradas. Si hace falta un conteo para un reporte, las
superficies de reportes merchant responden esa pregunta como se debe.

Un cursor inválido

{ "message": "The cursor parameter is invalid.", "error_code": "INVALID_CURSOR" }

422. Significa que el valor no era un cursor usable — normalmente uno armado a
mano, uno truncado, o uno de otra colección.

Relacionado

• Errores — el contrato completo de errores.
• Límites de uso — vale leerlo antes de recorrer todo en un bucle.