Paginazione

Tutti gli endpoint che restituiscono collezioni usano una paginazione a cursore. Il client non richiede un numero di pagina ma un puntatore opaco alla posizione successiva, restituito dalla chiamata precedente. Questo garantisce risultati coerenti anche quando la collezione cambia durante la lettura.

Parametri di query

Struttura della risposta

Ogni risposta paginata ha la stessa forma: un array data e un oggetto pagination.

{
  "data": [
    {
      "id": "sess_9f2c8d41",
      "projectId": "bp_proj_7f3a9c21",
      "clientId": "cli_5e1a7b30",
      "channel": "web",
      "status": "open",
      "messageCount": 14,
      "startedAt": "2026-09-04T09:12:44.006Z",
      "lastActivityAt": "2026-09-04T09:41:02.884Z",
      "createdAt": "2026-09-04T09:12:44.006Z"
    },
    {
      "id": "sess_3b7e0c58",
      "projectId": "bp_proj_7f3a9c21",
      "clientId": "cli_9d4f2a17",
      "channel": "whatsapp",
      "status": "closed",
      "messageCount": 6,
      "startedAt": "2026-09-04T08:55:10.412Z",
      "lastActivityAt": "2026-09-04T09:03:37.221Z",
      "createdAt": "2026-09-04T08:55:10.412Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InNlc3NfM2I3ZTBjNTgiLCJ0cyI6MTc4ODUxNTUzNX0",
    "hasMore": true,
    "total": 1234
  }
}

Ciclo di paginazione completo

const BASE_URL = 'https://api.blupantheon.com';
const API_KEY = process.env.BP_API_KEY!;

interface Page<T> {
  data: T[];
  pagination: { nextCursor: string | null; hasMore: boolean; total?: number };
}

export async function* paginate<T>(
  path: string,
  query: Record<string, string | number> = {},
): AsyncGenerator<T, void, undefined> {
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({
      limit: '200',
      ...Object.fromEntries(Object.entries(query).map(([k, v]) => [k, String(v)])),
    });
    if (cursor) params.set('cursor', cursor);

    const res = await fetch(`${BASE_URL}${path}?${params}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    if (!res.ok) {
      const err = await res.json();
      throw new Error(`${err.code}: ${err.message} (traceId ${err.traceId})`);
    }

    const page = (await res.json()) as Page<T>;
    for (const item of page.data) yield item;

    cursor = page.pagination.nextCursor;
  } while (cursor);
}

// Uso: scorre tutte le sessioni aperte del progetto senza caricarle tutte in memoria.
for await (const session of paginate('/console/v1/sessions', {
  projectId: 'bp_proj_7f3a9c21',
  status: 'open',
})) {
  console.log(session);
}

Filtri comuni

I filtri si combinano liberamente con la paginazione e si applicano prima dell'ordinamento. I filtri non riconosciuti vengono ignorati silenziosamente: verifica sempre di aver scritto correttamente il nome.

Esempio di combinazione tipica per una sincronizzazione incrementale notturna:

curl -sS -G "https://api.blupantheon.com/console/v1/clients" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  --data-urlencode "updatedAfter=2026-09-03T00:00:00Z" \
  --data-urlencode "status=active" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=200"

Ordinamento

L'ordinamento è sempre totale e deterministico: a parità di valore del campo scelto viene applicato un criterio secondario sull'identificativo della risorsa. Questo garantisce che nessun elemento venga saltato o restituito due volte durante la paginazione.

Un valore di sort non supportato produce 400 con codice VALIDATION_ERROR e l'elenco dei campi ammessi in details.

Limiti massimi

Stabilità del cursore

Durante una paginazione la collezione sottostante può cambiare. Il comportamento è il seguente:

• Gli elementi creati dopo l'inizio del ciclo non compaiono se l'ordinamento è discendente su createdAt; compaiono in coda se l'ordinamento è ascendente.
• Gli elementi eliminati durante il ciclo semplicemente non vengono restituiti: la pagina può contenere meno elementi di limit pur avendo hasMore a true.
• Gli elementi modificati durante il ciclo possono essere restituiti due volte se ordini per updatedAt in ordine ascendente. Deduplica sempre in base all'id quando elabori grandi volumi.

Errori frequenti