Guide de migration

Ce guide accompagne votre passage à Coffrify, que vous veniez d'un outil de transfert de fichiers grand public, d'une solution maison, ou d'une intégration construite sur une autre API. La logique reste la même : vous créez un transfert, vous obtenez des URL de téléversement, puis vous partagez un lien. Coffrify ajoute par-dessus l'hébergement en Union européenne, la conformité RGPD, le chiffrement AES-256-GCM côté serveur par défaut et un mode chiffrement de bout en bout optionnel où la clé ne quitte jamais votre poste. Vous trouverez ici la checklist de migration, les équivalences de concepts, les étapes concrètes et les pièges fréquents.

Checklist de migration

Avant de basculer le trafic de production, parcourez cette liste. Elle couvre l'essentiel d'une migration sereine, depuis la création des clés jusqu'à la bascule réelle.

• Créer un compte et générer une première clé d'API. Commencez par une clé de test cof_test_ ou une clé bac à sable cof_sandbox_ avant la production cof_live_.
• Attribuer les scopes nécessaires à la clé : transfers:write et transfers:read au minimum, plus webhooks:manage si vous branchez des notifications.
• Inventorier vos usages actuels : tailles de fichiers, durées d'expiration, nombre de téléchargements autorisés, présence d'un mot de passe ou d'un destinataire.
• Reproduire un premier transfert de bout en bout dans l'environnement de test, du POST /v1/transfers jusqu'au partage du lien.
• Mettre en place l'idempotence sur toutes vos écritures pour éviter les doublons lors des reprises sur erreur réseau.
• Brancher les webhooks et vérifier la signature des évènements reçus.
• Décider si vous activez le chiffrement de bout en bout pour tout ou partie de vos transferts.
• Basculer vers une clé cof_live_ et surveiller les en-têtes de limite de débit ainsi que le request_id dans vos logs.

Équivalences de concepts

Si vous venez d'un autre outil, le tableau suivant fait le pont entre le vocabulaire courant et les objets de l'API Coffrify. La plupart des notions ont un équivalent direct.

Étape 1 : créer une clé d'API

Toutes les requêtes s'authentifient avec un en-tête Authorization: Bearer <clé> sur la base https://api.coffrify.com/v1. Le préfixe de la clé choisit l'environnement : cof_live_ pour la production, cof_test_ pour les essais, cof_sandbox_ pour un bac à sable isolé qui expire au bout de 24 heures et reste hors facturation. Commencez vos tests avec une clé cof_test_ ou cof_sandbox_, attribuez-lui les scopes transfers:read et transfers:write, puis vérifiez l'accès.

curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_test_votre_cle"

Étape 2 : premier transfert

Un transfert se crée en déclarant les fichiers à envoyer. Vous fournissez pour chacun son name, sa size et son mime_type. Les champs expires_in_hours, max_downloads, password, recipient et transfer_title sont facultatifs. La réponse contient l'objet transfer (avec id, short_code, status, share_url, expires_at), un tableau upload_urls et le share_url. Pensez à joindre un en-tête Idempotency-Key (de 8 à 255 caractères) : une même clé rejouée renvoie X-Coffrify-Idempotent-Replay: true, et la même clé avec un corps différent renvoie une erreur 409.

curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_test_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: migration-001" \
  -d '{
    "files": [{ "name": "contrat.pdf", "size": 248000, "mime_type": "application/pdf" }],
    "expires_in_hours": 72,
    "max_downloads": 3,
    "transfer_title": "Contrat signe"
  }'

Téléversez ensuite chaque fichier en PUT vers l'URL correspondante de upload_urls, en reprenant les headers fournis pour cette entrée. Une fois les fichiers en place, partagez simplement le share_url. Vous pouvez lister vos transferts via GET /v1/transfers (paramètre limit jusqu'à 100, pagination par cursor avec has_more et next_cursor), puis récupérer ou supprimer un transfert avec GET /v1/transfers/{id} et DELETE /v1/transfers/{id}.

$ curl -X PUT "<upload_url>" \
    -H "Content-Type: application/pdf" \
    --data-binary @contrat.pdf
< HTTP/1.1 200 OK

Étape 3 : brancher les webhooks

Si votre ancienne intégration réagissait à des évènements (par exemple un téléchargement), reproduisez ce comportement avec un webhook. À la création, l'ensemble d'évènements par défaut est ["transfer.downloaded"] et vous recevez un secret de signature whsec_. Chaque appel est signé selon deux schémas en parallèle, et vous pouvez vous appuyer sur l'un ou l'autre : le standard Standard Webhooks via les en-têtes webhook-id, webhook-timestamp et webhook-signature (format v1,<base64 HMAC-SHA256(secret, id.timestamp.body)>), et le schéma historique via X-Coffrify-Signature (format t=<ts>,v1=<hex>). La tolérance d'horodatage est de 5 minutes. Vérifiez toujours la signature avant de traiter l'évènement.

Étape 4 : chiffrement de bout en bout (optionnel)

Par défaut, vos transferts sont chiffrés en AES-256-GCM côté serveur, dans l'Union européenne. Pour les contenus les plus sensibles, vous pouvez activer le mode chiffrement de bout en bout : la clé reste chez vous et le serveur ne lit jamais le contenu. Ce mode renforce la confidentialité, avec une contrepartie à intégrer dans vos procédures : si la clé est perdue, les données sont définitivement irrécupérables. Prévoyez donc une gestion fiable des clés côté client avant de l'activer en production.

• Mode serveur (par défaut) : chiffrement AES-256-GCM géré par Coffrify, données en UE, conforme RGPD.
• Mode bout en bout (optionnel) : la clé reste chez vous, le serveur ne lit pas le contenu.
• À retenir pour le bout en bout : clé perdue = données irrécupérables. Sauvegardez et transmettez vos clés de manière sûre.

Pièges fréquents

• Oublier l'idempotence : sans en-tête Idempotency-Key sur les écritures, une reprise après timeout réseau peut créer un transfert en double.
• Réutiliser une clé d'idempotence avec un corps différent : cela renvoie une erreur 409. Utilisez une clé distincte par opération logique.
• Confondre les environnements : une clé cof_test_ ou cof_sandbox_ ne voit pas les données de production. Vérifiez le préfixe avant la bascule.
• Ignorer les en-têtes de débit : surveillez X-RateLimit-Remaining et respectez Retry-After sur une réponse 429 plutôt que de réessayer immédiatement.
• Ne pas vérifier la signature des webhooks : traitez uniquement les évènements dont la signature est valide et l'horodatage dans la tolérance de 5 minutes.
• Scopes manquants : une clé sans le bon scope renvoie scope_missing. Attribuez transfers:write, transfers:read et webhooks:manage selon vos besoins.
• Activer le bout en bout sans plan de gestion des clés : la perte de la clé rend les données irrécupérables.

Gérer les erreurs

Toutes les erreurs suivent le même format : {"error":{"code","message","request_id"}}. Adaptez votre code de migration pour reconnaître les codes les plus courants et réagir correctement. Le request_id est précieux : conservez-le dans vos journaux pour tout échange avec le support.

Une fois ces étapes validées en test, basculez votre clé sur cof_live_ et déployez progressivement. Pour les langages autres que JavaScript et TypeScript, le SDK officiel coffrify n'existe pas encore (Python, Go, Ruby, PHP, Rust, Java et .NET arrivent bientôt) : appelez l'API REST directement en attendant. Votre migration est terminée lorsque vos transferts de production aboutissent, que vos webhooks sont vérifiés et que votre gestion des clés est en place si vous avez choisi le chiffrement de bout en bout.