Convenciones

Paginación por cursor

Por cursor, no por offset. Las listas de reservas, clientes, conductores, vehículos y eventos devuelven siempre la misma forma.

json

{
  "data": [
    "…"
  ],
  "next_cursor": "WyJib29raW5ncyIsIjIwMjYtMDktMTdUMTg6MDI6MTEuMjA0WiIsIjBjMWQyZTNmLTRhNWItNGM2ZC04ZTdmLTlhMGIxYzJkM2U0ZiJd.q1Zw8N3kPf2LgT7c",
  "has_more": true
}

Parámetro	Valor	Notas
`limit`	1 – 100, por defecto 25	Más de 100 se recorta a 100 sin error. Menos de 1 o no entero: 400 validation_error.
`cursor`	el `next_cursor` anterior	Opaco. Firmado y ligado al recurso: uno manipulado o de otra lista es 400 invalid_cursor.
`next_cursor`	string o null	null cuando no hay más páginas.
`has_more`	boolean	true si next_cursor no es null.

Cómo recorrer una lista

javascript

const base = 'https://wearetransfers.com/api/v1/bookings?status=completed&pickup_from=2026-09-01T00:00:00Z&limit=100';
let cursor = null;
do {
  const res = await fetch(cursor ? `${base}&cursor=${encodeURIComponent(cursor)}` : base, {
    headers: { Authorization: `Bearer ${process.env.WAT_API_KEY}` },
  });
  if (!res.ok) throw new Error(`${res.status} ${res.headers.get('x-wat-request-id')}`);
  const page = await res.json();
  for (const booking of page.data) await procesar(booking);
  cursor = page.next_cursor;
} while (cursor);

Repite los mismos filtros en cada página. El cursor guarda la posición, no los filtros.
El orden es created_at descendente (lo más nuevo primero) y, a igual fecha, id descendente. Es estable: una fila nueva no desplaza a las demás.
Un cursor no caduca por tiempo, pero la firma cambia si We Are Transfers rota su clave de firma. Si recibes invalid_cursor, vuelve a empezar desde la primera página.
El cursor nunca lleva la organización: la pone siempre la clave. No sirve para ver datos de otra empresa.

Sin cursor

GET /v1/webhooks devuelve todos (una integración tiene como mucho 10) y GET /v1/webhooks/{id}/deliveries devuelve las últimas limit entregas (1–100, por defecto 25) sin cursor. Ninguno de los dos trae next_cursor.

Cursor inválido:

json

{
  "error": {
    "code": "invalid_cursor",
    "message": "El cursor no es válido",
    "request_id": "req_9f8e7d6c5b4a39281706"
  }
}