Avant d'écrire votre premier appel, il est utile de partager le même vocabulaire que l'API Coffrify. Cette page rassemble les notions que vous croiserez partout dans la documentation : le transfert et ses fichiers, les URL de téléversement, le lien de partage, les environnements, les clés API et leurs scopes, l'idempotence, la réception et le coffre. Vous y trouverez aussi, sans détour, ce que signifie le chiffrement de bout en bout du point de vue de votre intégration. Tout ce qui suit s'applique à l'API REST v1, dont la base est https://api.coffrify.com/v1.
Le transfert
Un transfert est l'unité centrale de Coffrify : un envoi de un à plusieurs fichiers, partageable par un lien, avec sa propre durée de vie et ses règles d'accès. Vous le créez avec POST /v1/transfers. Chaque transfert reçoit un identifiant stable (id), un code court lisible (short_code), un status, une date d'expiration (expires_at) et un lien de partage (share_url). Le transfert ne devient consultable qu'une fois ses fichiers réellement téléversés.
/v1/transfersCrée un transfert et renvoie les URL de téléversement et le lien de partage.Les fichiers (files)
Vous déclarez le contenu d'un transfert via le tableau files. Chaque entrée décrit un fichier par son nom (name), sa taille en octets (size) et son type MIME (mime_type). Vous ne transmettez pas encore les octets à cette étape : vous annoncez seulement ce que vous comptez envoyer, ce qui permet à Coffrify de préparer une URL de téléversement par fichier. Le tableau files doit contenir au moins une entrée.
Les URL de téléversement (upload_urls)
La réponse de création contient upload_urls, un tableau qui associe à chaque fichier une URL d'envoi direct. Chaque entrée comporte un file_id, une url et un objet headers à reproduire tel quel. Vous téléversez le contenu en envoyant une requête PUT vers chaque url, avec ces headers, puis le transfert est prêt à être partagé. Ces URL sont temporaires : générez le transfert, téléversez sans attendre, puis partagez.
Le lien de partage (share_url)
Le share_url est l'adresse que vous communiquez à vos destinataires pour qu'ils consultent et téléchargent le transfert. Il s'appuie sur le short_code du transfert et reste valable jusqu'à expiration ou épuisement des téléchargements. C'est la seule URL à diffuser : les upload_urls, elles, sont réservées à votre code pour l'envoi des octets et ne doivent jamais être partagées.
Options d'un transfert
À la création, plusieurs réglages encadrent le transfert. expires_in_hours fixe la durée de vie avant expiration. max_downloads plafonne le nombre de téléchargements autorisés. password ajoute un mot de passe que le destinataire devra saisir. recipient renseigne l'adresse e-mail du destinataire visé. transfer_title donne un titre lisible au transfert. Ces champs sont facultatifs : un transfert minimal ne requiert que files.
| Champ | Rôle |
|---|---|
| expires_in_hours | Durée de vie du transfert avant expiration |
| max_downloads | Nombre maximal de téléchargements autorisés |
| password | Mot de passe demandé au destinataire à l'ouverture |
| recipient | Adresse e-mail du destinataire visé |
| transfer_title | Titre lisible affiché pour le transfert |
Les environnements (test, live, sandbox)
Coffrify expose trois environnements, déterminés par le préfixe de votre clé. L'environnement live (cof_live_) traite vos données réelles et facturées. L'environnement test (cof_test_) reproduit le comportement de l'API sans affecter votre production. L'environnement sandbox (cof_sandbox_) est un espace isolé et éphémère, pensé pour expérimenter : il vit 24 heures, reste hors facturation et applique des garde-fous (jusqu'à 10 Mo par fichier, 10 fichiers par transfert, 25 transferts par 24 heures et 5 téléchargements par transfert). Les ressources créées en sandbox restent invisibles depuis une clé live ou test, et inversement.
Les clés API et les scopes
Chaque requête s'authentifie avec une clé API transmise dans l'en-tête Authorization: Bearer <clé>. Les clés portent le préfixe cof_ suivi de leur environnement. Il existe aussi des clés restreintes (cof_rk_) et des jetons MCP (cof_mcp_). Une clé n'autorise que les opérations couvertes par ses scopes : par exemple transfers:write pour créer un transfert, transfers:read pour le lister, ou intake:write pour ouvrir une réception. Si la clé ne porte pas le scope requis, l'API répond par une erreur scope_missing.
L'idempotence
Pour qu'un nouvel essai après un incident réseau ne crée pas deux fois la même ressource, ajoutez un en-tête Idempotency-Key (de 8 à 255 caractères) sur vos écritures. Si vous rejouez la même clé avec le même corps, Coffrify renvoie la réponse d'origine et ajoute l'en-tête X-Coffrify-Idempotent-Replay: true. Si vous réutilisez la même clé avec un corps différent, l'API répond par une erreur 409. Utilisez donc une clé fraîche pour chaque opération distincte.
La réception (intake)
La réception, ou *intake*, inverse le sens du transfert : au lieu d'envoyer des fichiers, vous ouvrez un point de dépôt par lequel des tiers vous transmettent des documents. Vous créez une réception avec POST /v1/intakes. La réponse fournit une clé publiable (cip_), sûre à exposer dans un navigateur pour le dépôt côté client, tandis que la clé secrète reste votre clé cof_ côté serveur. Les documents reçus sont accessibles via /v1/intakes/{id}/documents.
Le coffre
Un coffre est un espace de fichiers persistant, à la manière d'une *data room*, par opposition au transfert qui est par nature temporaire. Là où un transfert sert à faire circuler des fichiers puis à expirer, le coffre conserve des documents dans la durée et organise leur accès. Utilisez le transfert pour partager ponctuellement, et le coffre pour héberger un ensemble de documents que vous voulez retrouver et structurer.
Le chiffrement, du point de vue de l'usage
Par défaut, vos fichiers sont chiffrés côté serveur en AES-256-GCM et hébergés dans l'Union européenne, dans le respect du RGPD. Vous pouvez aussi activer le chiffrement de bout en bout, dit *zero-knowledge* : dans ce mode, la clé reste chez vous et le serveur ne lit jamais le contenu. La contrepartie est simple à retenir : si cette clé est perdue, les données deviennent irrécupérables, y compris par Coffrify. Choisissez ce mode lorsque la confidentialité prime sur la possibilité de récupération assistée.