Organiser les fichiers avec dossiers et collections imbriqués

L'API Coffrify expose deux primitives complémentaires pour organiser vos transferts. Les dossiers (/v1/folders) regroupent visuellement des transferts à l'intérieur d'un workspace : chaque dossier porte un nom et une couleur hexadécimale, et les transferts qu'il contient deviennent non classés (unfiled) si le dossier est supprimé. Les collections (/v1/collections) sont des espaces partageables, dotés d'un slug public, d'une page de couverture personnalisable et d'une arborescence de sections et d'items positionnables. Les deux ressources sont isolées par environnement (live vs sandbox) et par workspace.

Endpoints disponibles

Les deux primitives se répartissent sur deux familles d'endpoints : /v1/folders pour les dossiers et /v1/collections (avec ses sous-ressources sections et items) pour les collections. En voici la liste complète.

Authentification

Toutes les requêtes doivent inclure votre clé API dans l'en-tête Authorization: Bearer <clé>. Les clés de test commencent par cof_test_…, les clés de production par cof_live_… et les clés sandbox par cof_sandbox_…. Les opérations de lecture nécessitent le scope folders:read (pour les dossiers) ou collections:read (pour les collections). Les opérations d'écriture (création, modification, suppression) nécessitent folders:manage ou collections:manage. La gestion des sections utilise le scope transfers:write.

Corps de la requête, Créer un dossier (POST /v1/folders)

Un dossier se résume à un nom et une couleur optionnelle. Le tableau ci-dessous détaille les champs de POST /v1/folders.

Corps de la requête, Créer une collection (POST /v1/collections)

Une collection demande un nom et accepte un slug, une couverture et des options de téléchargement. Voici les champs disponibles.

Corps de la requête, Ajouter un item (POST /v1/collections/{id}/items)

Pour peupler une collection, vous y ajoutez des transferts un par un. Le seul champ requis est transfer_id.

Exemples d'appels

Les exemples ci-dessous enchaînent la création d'un dossier, d'une collection et l'ajout d'un item. Choisissez votre langage.

# 1. Créer un dossier
curl -X POST https://api.coffrify.com/v1/folders \
  -H 'Authorization: Bearer cof_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Due Diligence 2024", "color": "#FF6B6B"}'
 
# 2. Créer une collection
curl -X POST https://api.coffrify.com/v1/collections \
  -H 'Authorization: Bearer cof_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Data Room M&A", "slug": "data-room-ma", "is_active": true, "allow_download": false, "watermark_enabled": true}'
 
# 3. Ajouter un transfert à la collection
curl -X POST https://api.coffrify.com/v1/collections/col_01HZ.../items \
  -H 'Authorization: Bearer cof_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"transfer_id": "tr_01HZ...", "label": "Bilan financier 2023", "position": 10}'

Réponse, Dossier créé (201)

La réponse renvoie l'id du dossier (à réutiliser pour y ranger des transferts), son name et sa color.

{
  "id": "fld_01HZK3X7Y8ABCDEF",
  "name": "Due Diligence 2024",
  "color": "#FF6B6B",
  "created_at": "2026-06-06T09:12:44.123Z"
}

Réponse, Collection récupérée (200 GET /v1/collections/{id})

La lecture d'une collection renvoie ses métadonnées ainsi que ses sections et ses items imbriqués, dans l'ordre d'affichage public.

{
  "id": "col_01HZK3X7Y8ABCDEF",
  "slug": "data-room-ma",
  "name": "Data Room M&A",
  "description": null,
  "subtitle": "Documents pour la phase de due diligence",
  "description_markdown": null,
  "logo_url": null,
  "cover_color": "#1A1A2E",
  "cover_image_url": null,
  "is_active": true,
  "show_powered_by": true,
  "allow_download": false,
  "watermark_enabled": true,
  "expires_at": "2026-12-31T23:59:59.000Z",
  "created_at": "2026-06-06T09:12:44.123Z",
  "updated_at": "2026-06-06T09:12:44.123Z",
  "sections": [
    {
      "id": "sec_01HZK3",
      "name": "Financier",
      "description": "Bilans et comptes de résultat",
      "position": 0,
      "is_visible": true,
      "created_at": "2026-06-06T09:14:00.000Z"
    }
  ],
  "items": [
    {
      "id": "ci_01HZK3X9",
      "transfer_id": "tr_01HZ...",
      "section_id": "sec_01HZK3",
      "position": 10,
      "label": "Bilan financier 2023",
      "description": null,
      "is_visible": true,
      "added_at": "2026-06-06T09:15:22.000Z"
    }
  ]
}

Réponse, Suppression (200)

{ "id": "fld_01HZK3X7Y8ABCDEF", "object": "folder", "deleted": true }

Erreurs

Ces erreurs valent pour les dossiers et les collections. Un 404 signale généralement un identifiant appartenant à un autre workspace (l'isolation est stricte).

Voir aussi

• Créer et envoyer un transfert
• Gérer les destinataires et les accès
• Authentification et scopes API
• Référence complète, Dossiers
• Référence complète, Collections