📄

Data Rooms & Collections·Débutant·10 min

Organiser : dossiers, collections et coffres

Apprenez à structurer vos transferts avec des dossiers, à publier des vitrines partageables via les collections et à créer des espaces sécurisés avec les coffres.

Télécharger en PDF

L'API Coffrify propose trois primitives complémentaires pour organiser vos transferts. Les dossiers (/v1/folders) sont de simples étiquettes de couleur que vous assignez à un transfert : ils n'affectent pas le lien public mais facilitent le filtrage en tableau de bord. Les collections (/v1/collections) sont des vitrines partageables qui regroupent plusieurs transferts en sections ordonnées, avec une page publique personnalisable (logo, couleur, filigrane). Les coffres (/v1/coffres) vont plus loin : ce sont des espaces sécurisés avec contrôle d'accès par e-mail ou mot de passe, NDA intégré, journalisation des vues et invitation de guests nominals. Ces trois ressources coexistent dans le même workspace et s'adressent à des cas d'usage distincts.

Endpoints couverts

Les trois primitives se répartissent sur autant de familles d'endpoints : /v1/folders pour les dossiers, /v1/collections pour les collections publiques et /v1/coffres pour les espaces sécurisés. En voici la liste complète.

GET/v1/foldersListe tous les dossiers du workspace courant.POST/v1/foldersCrée un dossier nommé et coloré.PATCH/v1/folders/{id}Renomme ou recolore un dossier existant.DELETE/v1/folders/{id}Supprime un dossier (les transferts qu'il contenait deviennent non classés).PUT/v1/transfers/{id}/folderAssigne un transfert à un dossier.DELETE/v1/transfers/{id}/folderRetire un transfert de son dossier (non classé).GET/v1/collectionsListe toutes les collections.POST/v1/collectionsCrée une collection (vitrine publique de transferts).GET/v1/collections/{id}Récupère une collection avec ses sections et items.PATCH/v1/collections/{id}Met à jour les métadonnées d'une collection.DELETE/v1/collections/{id}Supprime une collection (cascade sur items et sections).

POST/v1/collections/{id}/itemsAjoute un transfert à une collection.

POST/v1/collections/{id}/sectionsCrée une section dans une collection.GET/v1/coffresListe tous les coffres du workspace.POST/v1/coffresCrée un coffre sécurisé.GET/v1/coffres/{id}Récupère un coffre avec ses sections et items imbriqués.PATCH/v1/coffres/{id}Met à jour les champs du coffre (titre, statut, sécurité, watermark, NDA).POST/v1/coffres/{id}/itemsAjoute un item au coffre (kind : transfer, external_url ou markdown).POST/v1/coffres/{id}/guestsInvite un guest nominatif par e-mail.

Authentification et scopes

Toutes les requêtes doivent porter 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 scopes requis par ressource sont les suivants : lecture des dossiers folders:read, création/modification/suppression de dossiers et assignation de transferts folders:manage ; lecture des collections collections:read, création/modification/suppression de collections et de leurs items collections:manage ; lecture des coffres et de leurs sections transfers:read, création/modification/suppression de coffres et de leurs items/sections transfers:write ; gestion des guests d'un coffre coffres:manage.

Partie 1 : Dossiers

Les dossiers sont le moyen le plus simple de classer vos transferts en interne. Ils n'affectent jamais l'URL publique d'un transfert : c'est purement organisationnel.

Créer un dossier et y ranger un transfert

La création d'un dossier ne demande qu'un nom et une couleur. Vous rangez ensuite un transfert dedans avec PUT /v1/transfers/{id}/folder. Voici les champs acceptés.

Champ	Type	Requis	Description
name	string	Oui	Nom du dossier (sera tronqué si vide).
color	string	Non	Couleur hexadécimale (#007AFF par défaut).

# 1. Créer un dossier
curl -X POST https://api.coffrify.com/v1/folders \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Clients 2026", "color": "#22c55e"}'
 
# 2. Assigner un transfert au dossier (remplacer les IDs)
curl -X PUT https://api.coffrify.com/v1/transfers/trf_abc123/folder \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "fld_xyz789"}'

Réponse : création d'un dossier

La réponse renvoie l'id du dossier (à réutiliser pour y ranger des transferts), son name et sa color. Conservez l'id : c'est lui qui identifie le dossier dans tous les appels suivants.

{
  "id": "fld_xyz789",
  "name": "Clients 2026",
  "color": "#22c55e",
  "created_at": "2026-06-06T09:15:00.000Z"
}

Réponse : assignation d'un transfert à un dossier

{
  "transfer_id": "trf_abc123",
  "folder_id": "fld_xyz789"
}

Supprimer ou renommer un dossier

Un PATCH /v1/folders/{id} accepte name (string) et/ou color (string). Si aucun champ valide n'est fourni, l'API retourne 400 validation_error. Un DELETE /v1/folders/{id} supprime le dossier : les transferts qu'il contenait deviennent non classés (leur folder_id est mis à null automatiquement).

Partie 2 : Collections

Une collection est une page publique qui rassemble plusieurs transferts sous forme de liste ou de sections thématiques. Elle possède un slug unique dans le workspace (auto-calculé depuis name si absent), un logo, une couleur de couverture, une option de filigrane et une date d'expiration. Le champ is_active détermine si la page est accessible publiquement.

Corps de la requête : POST /v1/collections

Une collection se crée avec un nom et, optionnellement, une description et un mode d'affichage. Le slug public est généré automatiquement s'il n'est pas fourni. Voici les champs disponibles.

Champ	Type	Requis	Description
name	string	Oui	Nom affiché de la collection.
slug	string	Non	Slug URL (auto-dérivé de name si absent, 64 chars max).
description	string	Non	Description courte en texte brut.
subtitle	string	Non	Sous-titre affiché sous le nom.
description_markdown	string	Non	Description longue en Markdown.
logo_url	string	Non	URL publique du logo.
cover_color	string	Non	Couleur hexadécimale de la bannière.
cover_image_url	string	Non	URL d'image de couverture.
is_active	boolean	Non	Active la page publique (true par défaut).
show_powered_by	boolean	Non	Affiche le badge Coffrify (true par défaut).
allow_download	boolean	Non	Autorise le téléchargement des fichiers (true par défaut).
watermark_enabled	boolean	Non	Active le filigrane sur les documents (false par défaut).
expires_at	string (ISO 8601)	Non	Date d'expiration de la collection.

# Créer une collection
curl -X POST https://api.coffrify.com/v1/collections \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Livrables Q2 2026",
    "slug": "livrables-q2-2026",
    "description": "Tous les livrables du trimestre.",
    "allow_download": true,
    "watermark_enabled": false,
    "is_active": true
  }'
 
# Ajouter un transfert à la collection (remplacer COLLECTION_ID et TRANSFER_ID)
curl -X POST https://api.coffrify.com/v1/collections/COLLECTION_ID/items \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_id": "trf_abc123",
    "label": "Rapport final",
    "position": 0,
    "is_visible": true
  }'

Réponse : GET /v1/collections/{id}

La lecture d'une collection renvoie ses métadonnées ainsi que ses sections et ses items imbriqués. C'est la structure exacte que rend la page publique correspondante.

{
  "id": "col_def456",
  "slug": "livrables-q2-2026",
  "name": "Livrables Q2 2026",
  "description": "Tous les livrables du trimestre.",
  "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": null,
  "created_at": "2026-06-06T09:20:00.000Z",
  "updated_at": "2026-06-06T09:20:00.000Z",
  "sections": [
    {
      "id": "sec_ghi789",
      "name": "Documents contractuels",
      "description": null,
      "position": 0,
      "is_visible": true,
      "created_at": "2026-06-06T09:22:00.000Z"
    }
  ],
  "items": [
    {
      "id": "itm_jkl012",
      "transfer_id": "trf_abc123",
      "section_id": "sec_ghi789",
      "position": 0,
      "label": "Rapport final",
      "description": null,
      "is_visible": true,
      "added_at": "2026-06-06T09:23:00.000Z"
    }
  ]
}

Partie 3 : Coffres

Les coffres (/v1/coffres) sont des espaces de partage sécurisés conçus pour des échanges sensibles : due diligence, M&A, livraisons contractuelles. Ils prennent en charge la protection par mot de passe (hashé SHA-256 côté API), la vérification e-mail, la liste blanche d'adresses (allowed_emails), un NDA intégré (require_nda + nda_text), un filigrane configurable et des guests nominatifs. Chaque coffre possède un statut draft, active ou archived.

Corps de la requête : POST /v1/coffres

Un coffre se distingue d'une collection par ses options de confidentialité (mot de passe, watermark, NDA, accès nominatif). Le tableau ci-dessous détaille les champs de création.

Champ	Type	Requis	Description
title	string	Oui	Titre du coffre.
slug	string	Non	Slug URL (auto-généré si absent, unicité garantie dans le workspace).
description	string	Non	Description courte.
cover_color	string	Non	Couleur hex 6 chiffres, ex. #5d50ec (défaut).
cover_emoji	string	Non	Emoji de couverture (défaut : 🗄️).
status	string	Non	draft (défaut) ou active.
password	string	Non	Mot de passe en clair (haché SHA-256 avant stockage, active is_password_protected).
require_email_verification	boolean	Non	Demande une vérification e-mail aux visiteurs.
allowed_emails	array[string]	Non	Liste blanche d'adresses e-mail autorisées.
watermark_enabled	boolean	Non	Active le filigrane sur les fichiers.
watermark_text	string	Non	Texte personnalisé du filigrane.
require_nda	boolean	Non	Affiche un NDA à accepter avant l'accès.
nda_text	string	Non	Contenu textuel du NDA.
expires_at	string (ISO 8601)	Non	Date d'expiration du coffre.

# Créer un coffre sécurisé
curl -X POST https://api.coffrify.com/v1/coffres \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Data Room - Série A",
    "status": "active",
    "cover_color": "#5d50ec",
    "require_email_verification": true,
    "require_nda": true,
    "nda_text": "En accédant à ce coffre, vous acceptez la confidentialité des documents.",
    "watermark_enabled": true,
    "watermark_text": "CONFIDENTIEL"
  }'
 
# Ajouter une section
curl -X POST https://api.coffrify.com/v1/coffres/COFFRE_ID/sections \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Finances", "description": "Bilans et prévisionnels", "is_visible": true}'
 
# Ajouter un item (kind=transfer)
curl -X POST https://api.coffrify.com/v1/coffres/COFFRE_ID/items \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "transfer",
    "transfer_id": "trf_abc123",
    "section_id": "SECTION_ID",
    "custom_title": "Bilan 2025",
    "is_visible": true
  }'
 
# Inviter un guest
curl -X POST https://api.coffrify.com/v1/coffres/COFFRE_ID/guests \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "investisseur@example.com", "can_download": false}'

Réponse : GET /v1/coffres/{id}

La réponse expose le coffre complet, avec son slug, son title et ses items imbriqués. Notez les champs de sécurité (statut, protections) qui conditionnent l'accès des invités.

{
  "id": "cfr_mno345",
  "slug": "data-room-serie-a-a1b2",
  "title": "Data Room - Série A",
  "description": null,
  "cover_color": "#5d50ec",
  "cover_emoji": "🗄️",
  "status": "active",
  "view_count": 0,
  "unique_viewers": 0,
  "is_password_protected": false,
  "require_email_verification": true,
  "require_nda": true,
  "watermark_enabled": true,
  "watermark_text": "CONFIDENTIEL",
  "expires_at": null,
  "created_at": "2026-06-06T09:30:00.000Z",
  "sections": [
    {
      "id": "scs_pqr678",
      "coffre_id": "cfr_mno345",
      "title": "Finances",
      "description": "Bilans et prévisionnels",
      "position": 0,
      "is_visible": true,
      "created_at": "2026-06-06T09:31:00.000Z",
      "items": [
        {
          "id": "cfi_stu901",
          "section_id": "scs_pqr678",
          "kind": "transfer",
          "transfer_id": "trf_abc123",
          "external_url": null,
          "markdown_content": null,
          "custom_title": "Bilan 2025",
          "custom_description": null,
          "thumbnail_url": null,
          "position": 0,
          "is_visible": true,
          "created_at": "2026-06-06T09:32:00.000Z",
          "coffrify_transfers": {
            "id": "trf_abc123",
            "short_code": "Xk7pQ",
            "transfer_title": "Bilan 2025.pdf",
            "status": "active",
            "expires_at": null,
            "encryption_mode": "server"
          }
        }
      ]
    }
  ],
  "orphan_items": []
}

Réponse : invitation d'un guest

L'invitation crée un accès nominatif au statut pending jusqu'à ce que l'invité l'accepte. Chaque guest est tracé individuellement, ce qui permet de révoquer un accès sans impacter les autres.

{
  "guest": {
    "id": "gst_vwx234",
    "email": "investisseur@example.com",
    "status": "pending",
    "can_download": false,
    "note": null,
    "expires_at": null,
    "invite_token": "eyJhbGciOi...",
    "created_at": "2026-06-06T09:33:00.000Z",
    "invite_link": "https://app.coffrify.com/c/data-room-serie-a-a1b2?t=eyJhbGciOi..."
  },
  "invite_link": "https://app.coffrify.com/c/data-room-serie-a-a1b2?t=eyJhbGciOi..."
}

Erreurs communes

Ces erreurs valent pour les trois familles d'endpoints. Un 404 signale le plus souvent un identifiant appartenant à un autre workspace ou environnement (l'isolation est stricte).

Code HTTP	Code API	Quand	Résolution
400	validation_error	Champ obligatoire absent ou invalide (ex. `name` vide, `cover_color` non hexadécimal, `kind` inconnu).	Vérifiez les champs requis et leurs formats (hex 6 chiffres pour les couleurs, kind parmi `transfer`, `external_url`, `markdown`).
400	validation_error	Aucun champ valide envoyé dans un PATCH.	Incluez au moins un champ modifiable dans le corps.
400	validation_error	Invitation sur un coffre archivé.	Passez le coffre à `active` avant d'inviter des guests.
401	unauthorized	Clé API absente ou invalide.	Vérifiez l'en-tête `Authorization: Bearer cof_live_…`.
403	forbidden	Scope manquant (ex. `folders:manage` ou `coffres:manage`).	Créez une clé avec les scopes nécessaires ou contactez l'administrateur du workspace.
404	not_found	Ressource introuvable dans le workspace (dossier, collection, coffre, transfert ou section).	Vérifiez que l'ID appartient bien au workspace de la clé API.
409	validation_error	Slug de collection déjà utilisé dans le workspace.	Choisissez un slug différent ou laissez l'auto-génération (omettez le champ `slug`).
409	validation_error	Transfert déjà présent dans la collection.	Le même transfert ne peut apparaître qu'une fois par collection.
500	internal_error	Erreur base de données inattendue.	Retentez la requête. Si l'erreur persiste, contactez le support avec le `request_id` de la réponse.

Bonnes pratiques

Utilisez les dossiers pour le filtrage interne uniquement : ils ne changent pas l'URL publique d'un transfert. Préférez les collections pour partager un ensemble de fichiers à des clients ou partenaires : le champ is_active vous permet de dépublier instantanément sans supprimer le contenu. Pour des contextes sensibles (M&A, due diligence, levée de fonds), optez pour un coffre avec require_email_verification: true et watermark_enabled: true pour tracer chaque téléchargement. Les items d'un coffre supportent trois types (transfer, external_url, markdown) : utilisez markdown pour ajouter une introduction ou des instructions directement dans le coffre sans fichier supplémentaire. Supprimez les sections d'une collection plutôt que la collection entière : les items deviennent orphelins (section_id: null) mais restent accessibles.

Voir aussi

Créer et envoyer un transfert
Sécuriser un transfert : mot de passe, expiration, RGPD
Analytiques et téléchargements
Référence API complète, Dossiers
Référence API complète, Collections
Référence API complète, Coffres

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→