Paginación

Nuestra API utiliza paginación basada en cursores para todos los endpoints de listado. Esto permite recorrer grandes conjuntos de datos de manera eficiente y consistente, incluso cuando se insertan o eliminan registros entre solicitudes.

Parámetros

Parámetro	Tipo	Descripción
`limit`	entero	Número máximo de resultados a retornar. Por defecto es `10`, máximo `100`.
`starting_after`	string	Cursor opaco. Retorna resultados inmediatamente posteriores al objeto referenciado. Se usa para avanzar a la siguiente página.
`ending_before`	string	Cursor opaco. Retorna resultados inmediatamente anteriores al objeto referenciado. Se usa para retroceder a la página anterior.

Los parámetros starting_after y ending_before son mutuamente excluyentes. No se deben enviar ambos en la misma solicitud.

Formato de respuesta

Todos los endpoints de listado retornan un objeto con la siguiente estructura:

{
  "object": "list",
  "has_more": true,
  "has_previous": false,
  "next_cursor": "eyJpIjoiY3VzXzEyMyIsImMiOiIyMDI1LTAxLTAxIn0_a1b2c3d4",
  "previous_cursor": "eyJpIjoiY3VzXzEwMCIsImMiOiIyMDI1LTAxLTAyIn0_e5f6g7h8",
  "data": [
    { "id": "cus_123", "..." : "..." },
    { "id": "cus_124", "..." : "..." }
  ]
}

Campo	Tipo	Descripción
`object`	string	Siempre `"list"`.
`has_more`	boolean	`true` si existen más registros después de esta página.
`has_previous`	boolean	`true` si existen registros antes de esta página. Solo se incluye al navegar hacia atrás con `ending_before`.
`next_cursor`	string	Cursor para obtener la siguiente página. Usar como valor de `starting_after`. Solo presente cuando `data` tiene al menos un elemento.
`previous_cursor`	string	Cursor para obtener la página anterior. Usar como valor de `ending_before`. Solo presente cuando `data` tiene al menos un elemento.
`data`	array	Lista de objetos del recurso solicitado.

Uso

Primera página

Solicita el listado sin cursores:

curl https://api.ventipay.com/v1/customers?limit=3

{
  "object": "list",
  "has_more": true,
  "next_cursor": "eyJpIjoiY3VzXzMiLCJjIjoiMjAyNS0wMS0wMyJ9_a1b2c3d4",
  "previous_cursor": "eyJpIjoiY3VzXzEiLCJjIjoiMjAyNS0wMS0wMSJ9_e5f6g7h8",
  "data": [
    { "id": "cus_1" },
    { "id": "cus_2" },
    { "id": "cus_3" }
  ]
}

Siguiente página

Usa el valor de next_cursor como starting_after:

curl https://api.ventipay.com/v1/customers?limit=3&starting_after=eyJpIjoiY3VzXzMiLCJjIjoiMjAyNS0wMS0wMyJ9_a1b2c3d4

Página anterior

Usa el valor de previous_cursor como ending_before:

curl https://api.ventipay.com/v1/customers?limit=3&ending_before=eyJpIjoiY3VzXzEiLCJjIjoiMjAyNS0wMS0wMSJ9_e5f6g7h8

Notas

Los resultados se ordenan por fecha de creación descendente (created_at DESC). El registro más reciente aparece primero.
Los cursores son opacos. No deben construirse manualmente. Siempre utiliza los valores retornados por la API.
Los cursores no expiran, pero pueden dejar de ser válidos si el registro al que apuntan ha sido eliminado.
La paginación con limit y offset sigue siendo compatible por retrocompatibilidad, pero se recomienda usar cursores para recorridos de datos consistentes.
Cuando se usa starting_after o ending_before, el parámetro offset es ignorado.