Quickstart

Ce guide vous fait créer votre premier transfert de fichiers chiffré avec Coffrify, de la clé d'API au lien de partage, en quelques minutes. Le principe est toujours le même : vous décrivez les fichiers à l'API, elle vous renvoie des URL de téléversement signées, vous y déposez chaque fichier, puis vous partagez l'URL publique. Vous pouvez tout faire au choix avec le SDK JavaScript ou directement en REST. Tous les exemples utilisent une clé de test (cof_test_), sans facturation ni impact sur vos données de production.

Avant de commencer

Récupérez une clé d'API dans votre espace de travail, sous Console > Clés d'API. Pour ce guide, créez une clé de test avec le scope transfers:write (et transfers:read si vous voulez ensuite lister vos transferts). Une clé de test commence par cof_test_ ; basculez vers cof_live_ quand vous passez en production. La clé n'est affichée qu'une seule fois à sa création : conservez-la dans un gestionnaire de secrets, jamais dans votre code source ni côté navigateur.

L'API est accessible sur https://api.coffrify.com/v1. Chaque appel s'authentifie avec l'en-tête Authorization: Bearer <votre_clé>. Vos données sont hébergées dans l'Union européenne, en conformité RGPD.

export COFFRIFY_API_KEY="cof_test_..."

Vérifier votre clé

Avant de créer quoi que ce soit, validez que votre clé fonctionne avec un appel en lecture sur /v1/me. La réponse contient votre espace de travail, l'environnement résolu (test ici) et les scopes de la clé.

$ curl https://api.coffrify.com/v1/me \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"

Installer le SDK (optionnel)

Un SDK officiel existe aujourd'hui uniquement pour JavaScript / TypeScript (package @coffrify/sdk). Il fonctionne sous Node 18+, Deno, Bun, les navigateurs récents, Cloudflare Workers et Vercel Edge. Les SDK Python, Go, Ruby, PHP, Rust, Java et .NET arrivent bientôt : en attendant, appelez l'API REST directement, comme dans les onglets curl ci-dessous.

npm install @coffrify/sdk
# pnpm add @coffrify/sdk
# bun add @coffrify/sdk

Créer un transfert

Pour créer un transfert, vous décrivez chaque fichier par son name, sa size (en octets) et son mime_type. Vous pouvez ajouter des options : expires_in_hours pour la durée de validité, max_downloads pour plafonner les téléchargements, recipient pour l'adresse du destinataire, password pour protéger l'accès, et transfer_title pour un libellé lisible. Par défaut, vos fichiers sont chiffrés côté serveur en AES-256-GCM.

import { Coffrify } from "@coffrify/sdk";
 
const coffrify = new Coffrify({
  apiKey: process.env.COFFRIFY_API_KEY, // cof_test_... puis cof_live_...
});
 
const { transfer, upload_urls } = await coffrify.transfers.create(
  [{ name: "rapport.pdf", size: 1_240_000, mime_type: "application/pdf" }],
  {
    expires_in_hours: 72,
    max_downloads: 10,
    recipient: "client@example.com",
    password: "s3cret!",
    transfer_title: "Rapport trimestriel",
  },
);
 
console.log(transfer.short_code);

La réponse (201) contient l'objet transfer (avec id, short_code, status et expires_at), un tableau upload_urls (un objet { file_id, url, headers } par fichier, dans le même ordre que files), et le share_url à partager une fois les fichiers déposés.

{
  "transfer": {
    "id": "trf_...",
    "short_code": "abc123",
    "status": "pending",
    "expires_at": "2026-06-13T10:00:00.000Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport.pdf",
      "url": "https://...",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/abc123"
}

Téléverser chaque fichier

Pour chaque entrée de upload_urls, envoyez le contenu du fichier en PUT vers son url, en reprenant exactement les headers fournis. Tant qu'au moins un fichier n'est pas téléversé, le transfert reste inutilisable : c'est seulement après le dépôt que le lien de partage devient actif. Faites correspondre chaque upload_urls[i] au fichier files[i] du même indice.

import { readFile } from "node:fs/promises";
 
const body = await readFile("./rapport.pdf");
const target = upload_urls[0];
 
await fetch(target.url, {
  method: "PUT",
  headers: target.headers,
  body,
});

Partager le lien

Une fois tous les fichiers déposés, transmettez le share_url à votre destinataire (par exemple https://files.coffrify.com/abc123). Si vous avez défini un password, communiquez-le par un canal distinct. Le lien respecte la durée expires_in_hours et le plafond max_downloads que vous avez fixés à la création.

Bonnes pratiques dès le départ

• Envoyez un en-tête Idempotency-Key (8 à 255 caractères) sur chaque écriture : un rejeu renvoie la même réponse avec X-Coffrify-Idempotent-Replay: true, et la même clé avec un corps différent renvoie 409.
• Surveillez les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; sur un 429, respectez Retry-After avant de réessayer.
• En cas d'erreur, lisez l'enveloppe { "error": { "code", "message", "request_id" } } ; conservez le request_id (aussi renvoyé dans l'en-tête X-Request-Id) pour le support.
• Démarrez avec une clé cof_test_, puis remplacez-la par une clé cof_live_ pour la production, sans changer votre code.

Vous avez créé, téléversé et partagé votre premier transfert chiffré. Pour aller plus loin, listez vos transferts avec GET /v1/transfers, recevez des fichiers via la Réception (POST /v1/intakes), ou réagissez aux événements en temps réel avec les Webhooks.