Endpoint : Collections

Une collection regroupe plusieurs transferts sous une même page partageable, par exemple une data room, un espace client ou une remise de livrables. Au lieu d'envoyer un lien par fichier, vous publiez une seule adresse stable qui rassemble tout. Cette page couvre les quatre opérations sur la ressource collection elle-même : la créer, la lister, la mettre à jour et la supprimer. Toutes les requêtes utilisent la base https://api.coffrify.com/v1 et l'en-tête Authorization: Bearer <clé>.

Le modèle collection

Une collection porte un nom, un slug qui sert d'identifiant lisible dans l'URL publique, et plusieurs réglages d'affichage et de contrôle. Les champs que vous pouvez fournir et qui sont renvoyés sont les suivants.

Créer une collection

Seul name est obligatoire. Comme il s'agit d'une écriture, joignez un en-tête Idempotency-Key (8 à 255 caractères) pour pouvoir rejouer la requête sans créer de doublon. La réponse renvoie l'objet collection complet avec un statut 201.

curl -X POST https://api.coffrify.com/v1/collections \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f8c1a4e-collection-acme" \
  -d '{
    "name": "Espace client Acme",
    "slug": "acme",
    "description": "Documents partages avec Acme",
    "allow_download": true,
    "expires_at": "2026-12-31T23:59:59Z"
  }'

{
  "id": "col_8h2k9m4p",
  "slug": "acme",
  "name": "Espace client Acme",
  "description": "Documents partages avec Acme",
  "subtitle": null,
  "description_markdown": null,
  "logo_url": null,
  "cover_color": null,
  "cover_image_url": null,
  "is_active": true,
  "show_powered_by": true,
  "allow_download": true,
  "watermark_enabled": false,
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2026-06-10T09:14:02Z",
  "updated_at": "2026-06-10T09:14:02Z"
}

Lister les collections

La réponse est un objet liste : un champ object valant "list" et un tableau data contenant les collections, triées par date de création décroissante. Les collections créées avec une clé cof_sandbox_ sont isolées et n'apparaissent que dans l'environnement bac à sable.

$ curl https://api.coffrify.com/v1/collections \
    -H "Authorization: Bearer cof_live_..."

{
  "object": "list",
  "data": [
    {
      "id": "col_8h2k9m4p",
      "slug": "acme",
      "name": "Espace client Acme",
      "is_active": true,
      "allow_download": true,
      "expires_at": "2026-12-31T23:59:59Z",
      "created_at": "2026-06-10T09:14:02Z",
      "updated_at": "2026-06-10T09:14:02Z"
    }
  ]
}

Récupérer une collection

Récupérer une collection par son identifiant renvoie l'objet complet, enrichi de deux tableaux : items, la liste des transferts rattachés (avec transfer_id, position, label, is_visible), et sections, les regroupements de la page (avec name, position, is_visible). Pour gérer ces sous-ressources, utilisez les chemins /v1/collections/{id}/items et /v1/collections/{id}/sections.

Mettre à jour une collection

La mise à jour est partielle : ne transmettez que les champs à modifier, par exemple basculer is_active à false pour dépublier une collection ou ajuster expires_at. Vous pouvez remettre un champ texte à null pour l'effacer. Une requête PATCH sans aucun champ valide renvoie validation_error. Le slug n'est pas modifiable via PATCH.

curl -X PATCH https://api.coffrify.com/v1/collections/col_8h2k9m4p \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "description": "Espace cloture"
  }'

Supprimer une collection

La suppression retire la collection ainsi que ses items et ses sections rattachés. Les transferts sous-jacents ne sont pas supprimés : seuls leurs rattachements à la collection le sont. La réponse confirme l'opération.

{
  "id": "col_8h2k9m4p",
  "object": "collection",
  "deleted": true
}

Codes d'erreur

Les erreurs suivent le format commun {"error":{"code","message","request_id"}}. Le request_id figure aussi dans l'en-tête X-Request-Id de chaque réponse, à citer en cas de demande de support.