Dossiers, versions et corbeille

Organisez le contenu d'un coffre avec des dossiers, des fichiers et leur historique de versions, gérez les invités, restaurez depuis la corbeille et exportez l'ensemble en archive ZIP.

Un coffre (data room) regroupe des documents que vous conservez dans la durée et partagez avec des invités. Au-delà du simple dépôt de fichiers, l'API vous permet de structurer ce contenu en dossiers, de consulter une vue combinée dossiers + fichiers, de gérer les invités et leurs accès, de suivre l'historique des versions d'un fichier, de restaurer ce qui a été supprimé via la corbeille, et d'exporter tout le coffre en une archive ZIP. Cette page décrit ces opérations au travers des sous-ressources de /v1/coffres/{id} avec des exemples REST prêts à l'emploi. Les contenus sont hébergés en UE et chiffrés au repos ; pour un coffre en chiffrement de bout en bout, la clé reste chez vous et le serveur ne peut pas lire le contenu.

Les dossiers

Les dossiers servent à organiser hiérarchiquement le contenu d'un coffre, par exemple Juridique, Finances ou Annexes dans une data room de due diligence. Un dossier peut contenir des fichiers et d'autres dossiers. Vous les manipulez via /v1/coffres/{id}/folders.

POST/v1/coffres/{id}/foldersCrée un dossier dans le coffre. Indiquez son nom et, pour l'imbriquer, l'identifiant du dossier parent.

curl -X POST https://api.coffrify.com/v1/coffres/cof_dr_8K2p/folders \
  -H "Authorization: Bearer cof_xxx" \
  -H "Idempotency-Key: folder-juridique-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juridique",
    "parent_id": null
  }'

La réponse renvoie le dossier créé avec son id, que vous réutiliserez comme parent_id pour imbriquer un sous-dossier, ou comme folder_id au moment de téléverser un fichier. Pour lister l'arborescence, appelez GET /v1/coffres/{id}/folders.

Les fichiers

Les fichiers se gèrent via /v1/coffres/{id}/files. Comme ailleurs dans l'API, le dépôt se fait en deux temps : vous déclarez d'abord le fichier (nom, taille, type MIME, dossier de destination), le serveur vous renvoie une URL de téléversement, puis vous envoyez le contenu binaire vers cette URL avec les en-têtes fournis.

POST/v1/coffres/{id}/filesDéclare un fichier dans le coffre et renvoie l'URL de téléversement à utiliser pour envoyer le contenu.

# 1. Déclarer le fichier
curl -X POST https://api.coffrify.com/v1/coffres/cof_dr_8K2p/files \
  -H "Authorization: Bearer cof_xxx" \
  -H "Idempotency-Key: file-pacte-001" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "fld_3Qa7",
    "name": "pacte-associes.pdf",
    "size": 482113,
    "mime_type": "application/pdf"
  }'

$ curl -X PUT "https://upload.coffrify.com/..." \
    -H "Content-Type: application/pdf" \
    --data-binary @pacte-associes.pdf

La vue combinée des items

Pour afficher le contenu d'un coffre comme dans un explorateur de fichiers, l'endpoint /v1/coffres/{id}/items renvoie une vue combinée mêlant dossiers et fichiers d'un même niveau, triés ensemble. C'est l'appel idéal pour construire une navigation : chaque entrée porte un type (folder ou file) qui vous indique comment l'afficher.

GET/v1/coffres/{id}/itemsListe dossiers et fichiers d'un niveau du coffre. Passez ?folder_id=... pour explorer un sous-dossier.

curl https://api.coffrify.com/v1/coffres/cof_dr_8K2p/items?folder_id=fld_3Qa7 \
  -H "Authorization: Bearer cof_xxx"

Sans paramètre folder_id, vous obtenez le contenu de la racine. La réponse liste les items avec, pour chacun, son id, son type, son name et, pour les fichiers, la version courante et la taille.

Versions d'un fichier

Chaque fichier d'un coffre conserve un historique de versions. Lorsque vous redéposez un fichier portant le même nom au même emplacement, une nouvelle version est créée et le numéro version est incrémenté, sans perdre les versions précédentes. Cela vous permet de suivre l'évolution d'un document (par exemple un contrat révisé plusieurs fois) et de revenir en arrière si besoin.

Champ	Description
version	Numéro de la version courante du fichier (entier incrémenté à chaque dépôt).
created_at	Date de création de la version.
size	Taille de la version, en octets.

Pour consulter l'historique, listez les versions d'un fichier ; pour rétablir un état antérieur, restaurez la version voulue, qui redevient alors la version courante. Les versions plus anciennes restent consultables tant que le fichier existe dans le coffre.

# Historique des versions d'un fichier
curl https://api.coffrify.com/v1/coffres/cof_dr_8K2p/files/cfl_9TmR/versions \
  -H "Authorization: Bearer cof_xxx"

La corbeille et la restauration

La suppression d'un fichier ou d'un dossier n'est pas immédiate et définitive : l'élément part d'abord dans la corbeille du coffre. Vous pouvez ainsi le restaurer s'il a été supprimé par erreur, ou le purger définitivement. Pour supprimer un fichier, envoyez une requête DELETE sur sa ressource ; il devient alors restaurable depuis la corbeille.

# Envoie le fichier à la corbeille
curl -X DELETE \
  https://api.coffrify.com/v1/coffres/cof_dr_8K2p/files/cfl_9TmR \
  -H "Authorization: Bearer cof_xxx"

Invités et accès

Un coffre se partage avec des invités, gérés via /v1/coffres/{id}/guests. Vous invitez une personne par son adresse e-mail ; selon la configuration du coffre, l'accès peut être protégé par mot de passe, restreint à une liste d'adresses autorisées (allowed_emails), soumis à un accord de confidentialité (require_nda) ou marqué d'un filigrane (watermark_enabled). La gestion fine des invités vous laisse contrôler qui voit quoi.

POST/v1/coffres/{id}/guestsAjoute un invité au coffre par son adresse e-mail et déclenche son invitation.

curl -X POST https://api.coffrify.com/v1/coffres/cof_dr_8K2p/guests \
  -H "Authorization: Bearer cof_xxx" \
  -H "Idempotency-Key: guest-avocat-001" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "avocat@cabinet-exemple.fr",
    "name": "Maitre Durand"
  }'

Pour révoquer un accès, supprimez l'invité avec DELETE /v1/coffres/{id}/guests/{guest_id} : la personne perd immédiatement l'accès au coffre. Listez les invités existants et leur statut avec GET /v1/coffres/{id}/guests.

Exporter le coffre en ZIP

Pour récupérer l'intégralité d'un coffre, par exemple à des fins d'archivage ou de remise en fin de mission, déclenchez un export ZIP via POST /v1/coffres/{id}/export. L'archive respecte l'arborescence des dossiers. L'export étant potentiellement volumineux, il se prépare de façon asynchrone : l'appel renvoie un identifiant d'export et un statut, et l'URL de téléchargement devient disponible une fois l'archive prête.

POST/v1/coffres/{id}/exportGénère une archive ZIP de l'ensemble du coffre, dossiers et fichiers compris.

curl -X POST https://api.coffrify.com/v1/coffres/cof_dr_8K2p/export \
  -H "Authorization: Bearer cof_xxx" \
  -H "Idempotency-Key: export-dr8K2p-001"

Interrogez ensuite l'export jusqu'à ce que son status passe à ready : le champ download_url contient alors un lien temporaire vers l'archive. Pour être notifié automatiquement de la fin de génération plutôt que d'interroger en boucle, abonnez-vous aux événements de la famille coffre.* via un webhook.

En combinant dossiers, vue combinée d'items, versionnage et corbeille, vous disposez de tout le nécessaire pour piloter le contenu d'un coffre depuis votre code, tout en gardant la maîtrise des accès via les invités et la possibilité d'exporter l'ensemble à tout moment. Pensez à toujours fournir un en-tête Idempotency-Key sur les opérations d'écriture pour des appels sûrs et rejouables.