Opérations en masse

Dès que vous gérez des centaines ou des milliers de transferts, vous travaillez par lots plutôt qu'un objet à la fois. Cette page rassemble les techniques utiles pour les traitements en masse avec l'API REST v1 de Coffrify : parcourir l'intégralité d'une ressource avec la pagination par curseur, supprimer plusieurs transferts proprement, et rendre vos écritures répétées sûres grâce à l'idempotence. Toutes les requêtes ciblent la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>.

Parcourir tout avec la pagination par curseur

Les endpoints de liste renvoient une page à la fois. Plutôt qu'une pagination par décalage (offset), Coffrify utilise un curseur : un jeton opaque qui pointe vers l'endroit où reprendre. C'est ce qu'il vous faut pour un parcours en masse, parce que le curseur reste stable même si de nouveaux transferts sont créés pendant que vous itérez, sans ligne sautée ni dupliquée.

Chaque réponse de liste a la même forme. Le tableau data contient les objets de la page courante. has_more indique s'il reste des pages, et next_cursor porte le jeton à passer en paramètre cursor pour la page suivante (il vaut null sur la dernière page). Réglez la taille de page avec limit : la valeur par défaut est 20 et le maximum est 100.

{
  "object": "list",
  "data": [
    { "id": "tr_3f9a...", "short_code": "a1b2c3", "status": "active", "created_at": "2026-06-09T14:02:11Z" }
  ],
  "next_cursor": "MjAyNi0wNi0wOVQxNDowMjoxMVp8dHJfM2Y5YQ",
  "has_more": true,
  "limit": 100
}

La boucle de parcours est toujours la même : récupérez une page, traitez data, et tant que next_cursor n'est pas null, redemandez en le passant tel quel. Ne fabriquez jamais un curseur vous-même : c'est une valeur opaque, transmettez exactement ce que l'API vous a renvoyé.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
let cursor = undefined;
const all = [];
 
do {
  const page = await coffrify.transfers.list({ limit: 100, cursor });
  all.push(...page.data);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
 
console.log(`${all.length} transferts parcourus`);

Cette même mécanique de curseur s'applique aux autres listes de l'API, par exemple GET /v1/collections ou GET /v1/webhooks. Vous y retrouverez data, has_more et next_cursor à l'identique.

Supprimer plusieurs transferts

L'API supprime un transfert à la fois. Pour un nettoyage en masse, combinez le parcours par curseur ci-dessus avec un appel de suppression par identifiant. La suppression révoque le lien de partage en plus de retirer le transfert.

Une suppression réussie renvoie un accusé compact. Un identifiant inconnu (ou déjà supprimé) renvoie une erreur 404 avec le code not_found : traitez-la comme un cas attendu lors d'un balayage, pas comme un échec bloquant.

{ "id": "tr_3f9a...", "object": "transfer", "deleted": true }

// Supprimer tous les transferts expirés, page par page
let cursor = undefined;
let removed = 0;
 
do {
  const page = await coffrify.transfers.list({ status: 'expired', limit: 100, cursor });
  for (const t of page.data) {
    try {
      await coffrify.transfers.delete(t.id);
      removed++;
    } catch (err) {
      if (err.status !== 404) throw err; // déjà supprimé : on continue
    }
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
 
console.log(`${removed} transferts supprimés`);

Sécuriser les écritures répétées avec l'idempotence

Un script en masse retente forcément des appels : coupure réseau, délai dépassé, reprise après interruption. Sans précaution, un nouvel essai peut créer un doublon ou supprimer deux fois. L'en-tête Idempotency-Key règle ce problème : le serveur associe une réponse à la clé que vous fournissez, et tout rejeu de la même requête renvoie la réponse d'origine au lieu de la rejouer.

Joignez Idempotency-Key à vos appels d'écriture (POST, PUT, PATCH, DELETE). La clé doit faire entre 8 et 255 caractères ; un UUID convient parfaitement. Réutilisez la même clé pour chaque tentative d'une même opération logique, et changez-la pour chaque nouvelle opération.

import { randomUUID } from 'node:crypto';
 
const key = randomUUID(); // une clé par opération logique
 
async function createWithRetry(payload) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await coffrify.transfers.create(payload, { idempotencyKey: key });
    } catch (err) {
      if (attempt === 2 || err.status < 500) throw err;
    }
  }
}

Quand une requête est servie depuis le cache d'idempotence, la réponse porte l'en-tête X-Coffrify-Idempotent-Replay: true. Surveillez-le pour distinguer une exécution réelle d'un rejeu. Deux situations à connaître, toutes deux signalées par un statut 409 : si vous réutilisez une clé avec un corps de requête différent, vous recevez idempotency_conflict (prenez une clé neuve pour une requête différente) ; si un appel précédent portant la même clé est encore en cours de traitement, vous recevez idempotency_in_progress (réessayez après un court instant).

Les outils en masse du MCP

Si vous pilotez Coffrify depuis un assistant via le serveur MCP (https://mcp.coffrify.com/<workspace>, authentification par jeton cof_mcp_), deux outils couvrent directement les besoins en masse, sans écrire la boucle de pagination vous-même.

• coffrify_bulk_delete_transfers : supprimer plusieurs transferts en une seule opération. Nécessite le scope transfers:write.
• coffrify_bulk_export_transfers : produire un export JSON ou CSV de vos transferts (jusqu'à 10 000). Nécessite le scope transfers:read.
• coffrify_list_transfers et coffrify_search_transfers : parcourir et filtrer, avec la même pagination par curseur que l'API REST, en lecture seule (transfers:read).

Ces outils s'appuient sur la même API que celle décrite ici : mêmes scopes, même modèle de pagination, même isolation par environnement entre les clés de test et de production. Pour les opérations qui ne disposent pas d'un outil en masse dédié, revenez à l'API REST et combinez le parcours par curseur, la suppression par identifiant et l'idempotence présentés plus haut.