Pagination

Tous les points de terminaison qui renvoient une liste d'objets, comme GET /v1/transfers, paginent leurs résultats par curseur. Plutôt qu'un numéro de page, vous recevez à chaque réponse un jeton opaque (next_cursor) qui pointe vers la suite. Vous le renvoyez tel quel à l'appel suivant pour récupérer la page d'après. Ce modèle reste stable même quand de nouvelles ressources sont créées entre deux appels : aucune ligne n'est dupliquée ni sautée, contrairement à une pagination par décalage classique. Ce guide décrit les paramètres, les champs de réponse et la façon de parcourir un ensemble complet.

Paramètres de requête

Deux paramètres de chaîne de requête contrôlent la pagination. Ils s'ajoutent aux filtres propres à chaque point de terminaison (par exemple status ou search sur les transferts).

Champs de réponse

Une réponse de liste a la forme suivante. Le tableau data contient les éléments de la page courante, dans l'ordre antéchronologique (les plus récents d'abord).

{
  "object": "list",
  "data": [
    { "id": "tr_a1b2c3", "short_code": "x7K2mP", "status": "active", "created_at": "2026-06-10T14:32:00Z" }
  ],
  "has_more": true,
  "next_cursor": "eyJ0cyI6Ij...",
  "limit": 20
}

Récupérer la page suivante

Pour avancer d'une page, reprenez la valeur de next_cursor et placez-la dans le paramètre cursor de la requête suivante. Conservez les mêmes filtres et la même limit d'un appel à l'autre.

import { Coffrify } from "coffrify";
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
// Première page
const page1 = await coffrify.transfers.list({ limit: 20 });
console.log(page1.data.length, page1.has_more);
 
// Page suivante, si elle existe
if (page1.next_cursor) {
  const page2 = await coffrify.transfers.list({
    limit: 20,
    cursor: page1.next_cursor,
  });
  console.log(page2.data.length);
}

Parcourir tout l'ensemble

Pour traiter la totalité des résultats, bouclez tant que next_cursor n'est pas null, en réinjectant le curseur à chaque tour. L'exemple ci-dessous parcourt tous les transferts et les accumule dans un tableau.

import { Coffrify } from "coffrify";
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
async function listAllTransfers() {
  const all = [];
  let cursor = undefined;
 
  do {
    const page = await coffrify.transfers.list({ limit: 100, cursor });
    all.push(...page.data);
    cursor = page.next_cursor ?? undefined;
  } while (cursor);
 
  return all;
}
 
const transfers = await listAllTransfers();
console.log(`${transfers.length} transferts au total`);

Pièges courants

• Ne vous fiez pas à data.length < limit pour détecter la fin : utilisez next_cursor === null (ou has_more === false). Une page peut, dans de rares cas, contenir moins d'éléments que limit sans être la dernière.
• Ne réutilisez pas un curseur d'un point de terminaison ou d'un jeu de filtres sur un autre. Un curseur n'a de sens que pour la même liste, avec les mêmes filtres.
• Ne demandez pas plus de 100 éléments : toute valeur de limit au-delà est silencieusement ramenée à 100. Lisez le champ limit de la réponse pour connaître la valeur réellement appliquée.
• Gardez les filtres constants pendant la pagination. Changer status, search ou un autre filtre en cours de parcours invalide la cohérence du curseur.
• Ne stockez pas un curseur sur le long terme pour reprendre une liste plus tard : il reflète l'état au moment où il a été émis. Pour un instantané durable, parcourez l'ensemble en une fois.
• Conservez limit identique d'une page à l'autre. La changer en cours de route fonctionne, mais brouille le raisonnement sur le nombre d'appels restants.