R2 Connect API

Paginación y filtros

Cómo recorrer listas largas con cursores y cómo acotar resultados por fecha y estado.

Forma de una respuesta de lista#

Todos los recursos de lista responden con la misma estructura: data con los resultados y pagination con la información para continuar.

json

{
  "data": [ /* … */ ],
  "pagination": {
    "cursor": "g3QAAAACZAAEZGF0YWwAAAAB…",
    "has_more": true
  }
}

Cómo pedir la página siguiente#

Cuando has_more es true, pasa el valor de cursor en el parámetro del mismo nombre. Repite hasta que has_more sea false.

javascript

// Recorre TODAS las páginas
async function leerTodo(recurso, params = {}) {
  const todo = [];
  let cursor = null;

  do {
    const qs = new URLSearchParams({ ...params, limit: "50", ...(cursor ? { cursor } : {}) });
    const res = await fetch(`https://api.r2-os.com/api/connect/v1/${recurso}?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.R2_API_KEY}` },
    });
    if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error.message}`);

    const página = await res.json();
    todo.push(...página.data);
    cursor = página.pagination.has_more ? página.pagination.cursor : null;
  } while (cursor);

  return todo;
}

El cursor es opaco

No interpretes ni construyas cursores: son cadenas internas que pueden cambiar de forma. Úsalos tal cual los recibiste, y no los guardes por mucho tiempo. Para sincronizaciones incrementales usa created_from, no un cursor viejo.

Parámetros comunes#

Parámetro	Tipo	Descripción
limit	integer	Resultados por página. Entre 1 y 50. Predeterminado: 25.
cursor	string	Cursor de la página siguiente, tomado de `pagination.cursor`.
created_from	date	Fecha inicial, formato `AAAA-MM-DD` (UTC) o epoch en milisegundos.
created_to	date	Fecha final, inclusiva. Mismo formato.
status	string	Filtra por estado exacto.

Filtros de fecha#

Los filtros created_from y created_to se aplican sobre la fecha de creación del registro y aceptan dos formatos. created_to es inclusivo: incluye todo el día indicado.

bash

# Por fecha (UTC)
curl -H "Authorization: Bearer TU_LLAVE" \
  "https://api.r2-os.com/api/connect/v1/orders?created_from=2026-07-01&created_to=2026-07-31"

# Por epoch en milisegundos
curl -H "Authorization: Bearer TU_LLAVE" \
  "https://api.r2-os.com/api/connect/v1/orders?created_from=1782950400000"

Un formato distinto a esos dos responde 400 con el código bad_request.

Ordenamiento#

Las listas llegan de la más reciente a la más antigua por fecha de creación. Los clientes se ordenan por su última visita.

AnteriorAutenticación y permisos SiguienteLímites de uso