Téléverser des fichiers volumineux

Coffrify gère les gros transferts en deux temps. Vous décrivez d'abord les fichiers à POST /v1/transfers (nom, taille, type), l'API crée le transfert et vous renvoie une URL de téléversement signée par fichier, puis vous envoyez les octets directement vers ces URL avec une requête PUT. Aucun fichier ne transite par l'appel JSON initial : celui-ci ne porte que des métadonnées, ce qui rend la création instantanée même pour des fichiers de plusieurs gigaoctets. Ce guide détaille chaque étape, la gestion du parallélisme, la vérification du résultat et les limites de taille selon votre plan.

Le principe en deux temps

• Déclaration : vous appelez POST /v1/transfers avec un tableau files, chaque entrée portant name, size (en octets) et mime_type. La réponse contient upload_urls, une URL signée par fichier.
• Téléversement : pour chaque entrée de upload_urls, vous envoyez le contenu du fichier avec une requête PUT vers l'url fournie, en reprenant exactement les headers indiqués.
• Partage : une fois tous les fichiers téléversés, vous diffusez le share_url renvoyé. Le destinataire télécharge depuis ce lien.

1. Déclarer les fichiers

Envoyez un objet contenant files. Les champs optionnels expires_in_hours, max_downloads, password, recipient et transfer_title permettent de configurer le transfert dès sa création. Ajoutez un en-tête Idempotency-Key (8 à 255 caractères) pour rendre la création sûre au rejeu en cas de coupure réseau.

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer $COFFRIFY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "files": [
      { "name": "video-4k.mp4", "size": 8589934592, "mime_type": "video/mp4" },
      { "name": "dossier.pdf", "size": 12485760, "mime_type": "application/pdf" }
    ],
    "expires_in_hours": 168,
    "transfer_title": "Livraison client"
  }'

La réponse a le statut 201 et la forme suivante. L'ordre de upload_urls correspond à l'ordre de votre tableau files, et chaque entrée porte le file_id du fichier concerné.

{
  "transfer": {
    "id": "trf_3f9a2c8e1b",
    "short_code": "k7m2qp",
    "status": "active",
    "share_url": "https://files.coffrify.com/k7m2qp",
    "expires_at": "2026-06-17T09:30:00Z"
  },
  "upload_urls": [
    {
      "file_id": "video-4k.mp4",
      "url": "https://storage.coffrify.com/...signature...",
      "headers": { "Content-Type": "application/octet-stream" }
    },
    {
      "file_id": "dossier.pdf",
      "url": "https://storage.coffrify.com/...signature...",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/k7m2qp"
}

2. Téléverser vers les URL signées

Pour chaque entrée de upload_urls, envoyez le contenu binaire du fichier avec une requête PUT vers l'url. Reprenez exactement les headers renvoyés pour cette entrée : ils font partie de la signature et un en-tête manquant ou modifié fait échouer le téléversement. N'ajoutez pas votre clé API sur le PUT ; l'URL est déjà signée et s'authentifie seule.

import { readFile } from "node:fs/promises";
 
// Associez chaque file_id à son chemin local.
const paths = {
  "video-4k.mp4": "./video-4k.mp4",
  "dossier.pdf": "./dossier.pdf",
};
 
for (const u of upload_urls) {
  const body = await readFile(paths[u.file_id]);
  const put = await fetch(u.url, {
    method: "PUT",
    headers: u.headers, // verbatim, ne rien ajouter ni retirer
    body,
  });
  if (!put.ok) throw new Error(`Echec PUT ${u.file_id}: ${put.status}`);
}

Téléverser plusieurs fichiers en parallèle

Les URL de upload_urls sont indépendantes : vous pouvez lancer plusieurs PUT en même temps pour accélérer un transfert à nombreux fichiers. Restez raisonnable sur la concurrence (3 à 5 téléversements simultanés conviennent à la plupart des connexions) afin de ne pas saturer votre bande passante montante. L'exemple ci-dessous borne le parallélisme et réessaie un fichier en cas d'échec réseau.

async function uploadAll(uploadUrls, paths, { concurrency = 4 } = {}) {
  const queue = [...uploadUrls];
 
  async function worker() {
    while (queue.length) {
      const u = queue.shift();
      const body = await readFile(paths[u.file_id]);
      let attempt = 0;
      while (true) {
        const put = await fetch(u.url, { method: "PUT", headers: u.headers, body });
        if (put.ok) break;
        if (++attempt >= 3) throw new Error(`Echec PUT ${u.file_id}: ${put.status}`);
        await new Promise((r) => setTimeout(r, 1000 * attempt)); // backoff
      }
    }
  }
 
  await Promise.all(Array.from({ length: concurrency }, worker));
}

3. Vérifier le résultat

Une fois tous les PUT réussis (statut 200), le transfert est prêt et le share_url peut être diffusé. Pour confirmer côté serveur, interrogez le transfert par son identifiant. Un transfert exploitable a le statut active.

$ curl https://api.coffrify.com/v1/transfers/trf_3f9a2c8e1b \
    -H "Authorization: Bearer $COFFRIFY_KEY"
{
  "id": "trf_3f9a2c8e1b",
  "short_code": "k7m2qp",
  "status": "active",
  "expires_at": "2026-06-17T09:30:00Z"
}

Limites de taille selon le plan

La limite de taille s'applique à la somme des fichiers d'un même transfert, pas à chaque fichier pris isolément. Le nombre de transferts actifs en parallèle est lui aussi plafonné. La durée de conservation maximale dépend également de votre plan : si vous demandez un expires_in_hours supérieur au plafond, il est ramené à cette valeur.

Si la somme des size déclarés dépasse le plafond de votre plan, la création échoue avec un statut 400 et un message précisant la limite. Vérifiez donc la taille totale avant l'appel, ou répartissez vos fichiers sur plusieurs transferts.

Pour activer le mode chiffrement de bout en bout sur un gros transfert, la mécanique reste la même (déclaration puis PUT) : seule la clé de déchiffrement reste chez vous et le serveur ne lit pas le contenu. Gardez à l'esprit qu'une clé perdue rend les données irrécupérables. Pour le reste, la liste paginée de vos transferts (GET /v1/transfers, limit jusqu'à 100, curseur via next_cursor et has_more) vous permet de suivre l'ensemble de vos envois volumineux.