Votre premier transfert

Ce tutoriel vous guide pas à pas pour réaliser votre tout premier transfert avec l'API Coffrify. Vous allez créer un transfert avec POST /v1/transfers, téléverser le contenu de vos fichiers directement vers le stockage, puis récupérer un lien de partage prêt à envoyer. Vos données restent en Union européenne et sont chiffrées (AES-256-GCM côté serveur par défaut). Comptez quelques minutes : à la fin, vous aurez un lien share_url fonctionnel et vous saurez fixer une expiration, un nombre de téléchargements et un mot de passe.

Étape 1 : récupérer une clé API

Toutes les requêtes s'authentifient avec un jeton porteur dans l'en-tête Authorization: Bearer <clé>. Générez une clé depuis votre console Coffrify. Le préfixe indique l'environnement : cof_test_ pour le bac à sable de test, cof_live_ pour la production. Pour suivre ce guide sans facturation ni effet de bord, utilisez une clé cof_test_ ou une clé cof_sandbox_ (environnement isolé, purgé après 24 h). La création d'un transfert exige le scope transfers:write ; la lecture exige transfers:read.

Étape 2 : créer le transfert

Vous décrivez les fichiers à l'avance dans le tableau files, chacun avec son name, sa taille size en octets et son mime_type. Les autres champs sont facultatifs : expires_in_hours (durée de vie), max_downloads (plafond de téléchargements), password (protection par mot de passe), recipient (e-mail du destinataire) et transfer_title (libellé lisible). La base de l'API est https://api.coffrify.com/v1.

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer $COFFRIFY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfert-rapport-2026-06-10" \
  -d '{
    "files": [
      { "name": "rapport.pdf", "size": 482310, "mime_type": "application/pdf" }
    ],
    "expires_in_hours": 168,
    "max_downloads": 3,
    "transfer_title": "Rapport trimestriel"
  }'

La réponse a un statut 201 et contient trois éléments clés : l'objet transfer (avec id, short_code, status, expires_at), le tableau upload_urls (une entrée par fichier, dans le même ordre que files), et le share_url à partager une fois le téléversement terminé.

{
  "transfer": {
    "id": "trf_a1b2c3d4",
    "short_code": "k7Qm2x",
    "transfer_title": "Rapport trimestriel",
    "status": "pending",
    "expires_at": "2026-06-17T09:30:00Z",
    "max_downloads": 3
  },
  "upload_urls": [
    {
      "file_id": "rapport.pdf",
      "url": "https://upload.coffrify.com/...signature...",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/k7Qm2x"
}

Étape 3 : téléverser chaque fichier en PUT

Pour chaque entrée de upload_urls, envoyez le contenu binaire du fichier correspondant par une requête PUT vers son url. Reproduisez systématiquement les en-têtes fournis dans headers (par exemple Content-Type) : ils font partie de l'URL signée et le téléversement échoue s'ils manquent. La correspondance se fait par l'ordre du tableau, et file_id reprend le nom du fichier déclaré.

# upload.url et upload.headers proviennent de la réponse de l'étape 2
curl -X PUT "<upload_urls[0].url>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @rapport.pdf

Étape 4 : partager le lien

Une fois tous les fichiers téléversés, le transfert est prêt. Communiquez le share_url (forme https://files.coffrify.com/<short_code>) à votre destinataire par le canal de votre choix. Si vous avez renseigné recipient, Coffrify peut aussi notifier cette adresse. Le destinataire ouvre le lien, saisit le mot de passe le cas échéant, puis télécharge.

$ echo "Voici vos fichiers : https://files.coffrify.com/k7Qm2x"
Voici vos fichiers : https://files.coffrify.com/k7Qm2x

Étape 5 : vérifier le transfert

Contrôlez l'état à tout moment avec GET /v1/transfers/{id} : vous obtenez le transfert complet, sa liste de fichiers, le nombre de téléchargements déjà consommés et la date d'expiration. Pour parcourir l'historique, GET /v1/transfers renvoie une liste paginée par curseur (limit jusqu'à 100, plus cursor, has_more et next_cursor).

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

Aller plus loin : expiration et mot de passe

Vous contrôlez la durée de vie et l'accès dès la création. expires_in_hours fixe l'expiration (par exemple 24 pour une journée, 168 pour sept jours) ; passé ce délai, le lien cesse de fonctionner. max_downloads borne le nombre de récupérations. password impose un mot de passe au téléchargement : transmettez-le au destinataire par un canal distinct du lien. Combinés, ces trois réglages donnent un transfert à durée limitée, à diffusion plafonnée et protégé.

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer $COFFRIFY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contrat-confidentiel-01" \
  -d '{
    "files": [
      { "name": "contrat.pdf", "size": 91022, "mime_type": "application/pdf" }
    ],
    "expires_in_hours": 24,
    "max_downloads": 1,
    "password": "correct-cheval-pile-agrafe",
    "recipient": "client@exemple.fr",
    "transfer_title": "Contrat à signer"
  }'

En cas d'erreur, l'API renvoie un corps {"error":{"code","message","request_id"}} ; le même request_id figure dans l'en-tête X-Request-Id, à citer si vous contactez le support. Les codes les plus courants ici sont invalid_api_key (clé absente ou révoquée), scope_missing (la clé n'a pas transfers:write), validation_error (un champ comme files est manquant ou invalide), not_found (transfert inconnu) et rate_limited (trop de requêtes : consultez l'en-tête Retry-After). Vous savez désormais créer, téléverser, partager et vérifier un transfert de bout en bout.