Paginación

Las listas de clientes (GET /public/v1/clients), de direcciones (GET /public/v1/clients/{id}/addresses), de tareas (GET /public/v1/tasks), de la agenda (GET /public/v1/appointments), de presupuestos (GET /public/v1/quotes), de órdenes de servicio (GET /public/v1/service_orders), de tipos de orden (GET /public/v1/service_order_types) de equipo (GET /public/v1/team), de productos (GET /public/v1/products), de variaciones (GET /public/v1/products/{id}/variations), de categorías de producto (GET /public/v1/product_categories), del historial de stock (GET /public/v1/stock_movements), de servicios (GET /public/v1/services), de categorías de servicio (GET /public/v1/service_categories), de ventas (GET /public/v1/sales), de versiones de una venta (GET /public/v1/sales/{id}/versions), de movimientos (GET /public/v1/financial_transactions), de cuentas (GET /public/v1/financial_accounts) y de categorías de finanzas (GET /public/v1/financial_categories) ya siguen todo lo que está en esta página, y las de las próximas fases lo siguen igual. La Referencia es la lista de lo que responde hoy.

Cómo funciona

Una lista larga no sale en una sola respuesta. La API la corta en páginas y devuelve, junto con los datos, la marca de dónde se detuvo. Usted pide la página siguiente enviando esa marca de vuelta.

Dos cosas entran en la consulta:

Parámetro	Qué es
`limit`	Cuántos registros quiere en la página. Por defecto 20, máximo 100
`cursor`	La marca desde donde continuar. En la primera llamada, no lo envíe

La respuesta siempre tiene este formato:

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "Y3JlYXRlZF9hdDoy..."
}

Campo	Qué es
`object`	Siempre `"list"`. Así reconoce una respuesta de lista
`data`	Los registros de esta página, en el orden de la consulta
`has_more`	`true` cuando todavía existe una página después de esta
`next_cursor`	La marca para pedir la página siguiente

Qué guarda el cliente entre páginas

Solo el next_cursor. Nada más.

No guarde el número de la llamada, el total de registros leídos ni el último id visto para intentar continuar por él. El cursor ya lleva todo lo que la API necesita para retomar desde el lugar correcto.

Cómo saber que terminó

Deténgase cuando has_more sea false. Mientras sea true, envíe el next_cursor de vuelta en el parámetro cursor y pida otra vez.

No use el tamaño de data como señal de fin. Una página puede venir más chica que el limit y todavía tener continuación.

El cursor es opaco

El valor del cursor es un texto que solo la API entiende. Trátelo como caja negra:

No lo interprete. Parece legible en algunos casos, pero su contenido es asunto interno y puede cambiar sin aviso, porque eso no rompe a nadie que solo devuelve el valor.
No lo construya a mano. Un cursor inventado es rechazado.
No lo toque. Envíe exactamente el texto que llegó, sin cortar, sin decodificar, sin cambiar un carácter.

Por qué no existe número de página

Con número de página, la página 2 quiere decir “salte los primeros 20”. Si alguien crea un registro entre su llamada de la página 1 y la de la página 2, todo baja una posición: el vigésimo registro de la página 1 pasa a ser el primero de la página 2, y usted lo lee dos veces. Si alguien borra un registro, pasa lo contrario y un registro nunca aparece.

El cursor no cuenta posiciones, marca un punto en el ordenamiento. Un registro creado después de su primera página no empuja nada, y el recorrido termina sin repetir ni saltar.

Por eso tampoco existe offset ni page en la API.

Filtros y orden

Toda lista acepta los mismos tres filtros de fecha:

Filtro	Qué hace
`created_after`	Solo lo que se creó después de este instante
`created_before`	Solo lo que se creó antes de este instante
`updated_after`	Solo lo que cambió después de este instante

El orden por defecto es created_at descendente, del más nuevo al más antiguo.

Con updated_after, el orden pasa a ser updated_at ascendente. Ese es el modo de sincronización: usted guarda el mayor updated_at que vio, y en la próxima ronda continúa desde ahí, sin releer lo que no cambió. Las fechas siguen el formato de Fechas y dinero.

No existe ordenamiento libre ni filtro por campo arbitrario. Cada recurso declara sus propios filtros en la Referencia.

Próximo paso

Fechas y dinero: el formato de las fechas que aceptan los filtros.
Límites de uso: recorrer una lista larga gasta presupuesto de llamadas.