Paginación

Cuando la API devuelve una lista, los resultados se paginan automáticamente. GET /v2/documents (y sus alias, como los documentos de una carpeta) usa paginación por cursor — rápida y estable incluso con miles de registros. Algunos listados —p. ej. contactos y sesiones de onboarding— usan en cambio paginación por offset (page + pageSize, con total/totalPages en meta). Revisa el meta de cada respuesta para saber cuál aplica.

¿Cómo funciona?

Piensa en la paginación como pasar páginas de un libro:

Pides la primera página con un limit (cuántos resultados quieres)
La respuesta incluye un cursor — un token que apunta a la siguiente página
Usas ese cursor para pedir la siguiente página, y así sucesivamente
Cuando ya no hay más, hasNext es false y nextCursor es null

Primera petición

Envía una petición con los parámetros de paginación:

Name
limit
Type
integer
Description
Resultados por página (1-100). Por defecto: 10.
Name
scope
Type
string
Description
Filtro de alcance: owner (default), org, tenant, o accessible.
Name
sortBy
Type
string
Description
Campo para ordenar: created_at (default) o updated_at.
Name
sortOrder
Type
string
Description
Dirección: asc o desc (default).

Primera página

curl -G https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d scope=accessible \
  -d sortBy=created_at \
  -d sortOrder=desc

Respuesta paginada

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contrato.pdf",
      "createdAt": "2024-11-23T20:00:00Z"
    }
    // ... más documentos
  ],
  "meta": {
    "limit": 10,
    "hasNext": true,
    "nextCursor": "djF8Y3JlYXRlZF9hdHxkZXNjfDIw...",
    "prevCursor": null
  }
}

Siguiente página

Usa el nextCursor de la respuesta anterior como parámetro cursor:

Name
cursor
Type
string
Description
Token opaco obtenido del meta.nextCursor de la respuesta anterior.

Siguiente página

curl -G https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d cursor="djF8Y3JlYXRlZF9hdHxkZXNjfDIw..."

Respuesta

{
  "data": [
    // ... siguientes 10 documentos
  ],
  "meta": {
    "limit": 10,
    "hasNext": true,
    "nextCursor": "djF8Y3JlYXRlZF9hdHxkZXNjfDQw...",
    "prevCursor": null
  }
}

Última página

Sabes que llegaste al final cuando hasNext es false y nextCursor es null.

Hoy la paginación es solo hacia adelante. prevCursor siempre es null en toda respuesta (la navegación hacia atrás no está implementada). Construye tu paginación únicamente con nextCursor.

Última página

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Último documento.pdf",
      "createdAt": "2024-11-01T10:00:00Z"
    }
  ],
  "meta": {
    "limit": 10,
    "hasNext": false,
    "nextCursor": null,
    "prevCursor": null
  }
}