Endpoint : Fichiers

Un transfert Coffrify est un conteneur d'un ou plusieurs fichiers. Vous ne créez jamais un fichier isolément : vous le déclarez au moment où vous créez le transfert, puis vous téléversez son contenu vers une URL signée que l'API vous renvoie. Cette page décrit le cycle de vie complet d'un fichier : déclaration, téléversement, lecture des métadonnées et statut. Le chiffrement AES-256-GCM est appliqué côté serveur par défaut, dans l'Union européenne, sans aucune action de votre part.

Le modèle en deux temps

La création d'un transfert ne transporte aucun octet de contenu. L'appel POST /v1/transfers envoie uniquement la liste des fichiers attendus (leur nom, leur taille et leur type), et l'API répond avec une URL de téléversement par fichier. Vous réalisez ensuite un PUT direct vers chacune de ces URL pour y déposer le contenu. Tant qu'un fichier n'a pas été téléversé, le transfert n'est ni lisible ni partageable.

1. Déclarer les fichiers avec POST /v1/transfers (un objet par fichier dans files[]).
2. Téléverser chaque contenu par un PUT vers l'url reçue, en envoyant les headers fournis.
3. Lire ensuite les métadonnées et le statut via GET /v1/transfers/{id} ou GET /v1/transfers/{id}/files.

Déclarer les fichiers

Chaque entrée de files[] accepte trois champs. Le champ name est le nom de fichier affiché au destinataire. Le champ size est la taille en octets : il sert à préparer le téléversement et doit correspondre au contenu réellement envoyé. Le champ mime_type décrit le type de contenu (par exemple application/pdf) ; en son absence, application/octet-stream est utilisé.

const res = await fetch("https://api.coffrify.com/v1/transfers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COFFRIFY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    transfer_title: "Contrat signé",
    expires_in_hours: 72,
    max_downloads: 3,
    files: [
      { name: "contrat.pdf", size: 482113, mime_type: "application/pdf" },
      { name: "annexe.docx", size: 91240, mime_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" },
    ],
  }),
});
const transfer = await res.json();

La réponse contient le transfert créé, la liste upload_urls (une entrée par fichier déclaré) et l'share_url de partage. Chaque entrée de upload_urls expose le file_id (qui reprend le nom du fichier), l'url signée à utiliser pour le PUT, et les headers exacts à transmettre lors du téléversement.

{
  "transfer": {
    "id": "trf_8sK2mPq...",
    "short_code": "a1b2c3",
    "status": "pending",
    "expires_at": "2026-06-13T09:00:00.000Z",
    "max_downloads": 3
  },
  "upload_urls": [
    {
      "file_id": "contrat.pdf",
      "url": "https://...signed-upload-url...",
      "headers": { "Content-Type": "application/octet-stream" }
    },
    {
      "file_id": "annexe.docx",
      "url": "https://...signed-upload-url...",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/a1b2c3"
}

Téléverser le contenu

Pour chaque entrée de upload_urls, effectuez un PUT du contenu binaire vers l'url, en envoyant les headers fournis tels quels. N'ajoutez pas d'en-tête Authorization sur ces requêtes : l'autorisation est portée par la signature présente dans l'URL. Les URL de téléversement sont temporaires ; téléversez sans tarder après la création.

import { readFile } from "node:fs/promises";
 
for (const slot of transfer.upload_urls) {
  const contents = await readFile(`./${slot.file_id}`);
  const put = await fetch(slot.url, {
    method: "PUT",
    headers: slot.headers, // en-têtes fournis par l'API
    body: contents,
  });
  if (!put.ok) throw new Error(`Téléversement échoué pour ${slot.file_id}`);
}
 
console.log("Partagez :", transfer.share_url);

Lister les fichiers d'un transfert

Une fois les fichiers téléversés, cet endpoint renvoie leurs métadonnées. La réponse expose object: "list", le tableau data des fichiers, le nombre file_count et le volume cumulé total_bytes (en octets). Chaque fichier porte un identifiant id, son file_name, sa taille file_size, son type file_type et sa date created_at.

$ curl https://api.coffrify.com/v1/transfers/trf_8sK2mPq.../files \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"
 
{
  "transfer_id": "trf_8sK2mPq...",
  "short_code": "a1b2c3",
  "object": "list",
  "data": [
    {
      "id": "file_4Df9...",
      "file_name": "contrat.pdf",
      "file_size": 482113,
      "file_type": "application/pdf",
      "created_at": "2026-06-10T09:00:01.000Z"
    }
  ],
  "file_count": 1,
  "total_bytes": 482113
}

Les métadonnées des fichiers sont également incluses dans le détail du transfert. Un GET /v1/transfers/{id} renvoie l'objet transfert complet accompagné d'un tableau files, où chaque entrée expose id, file_name, file_size, file_type et created_at. C'est pratique pour récupérer en un seul appel le statut du transfert et la composition de ses fichiers.

Statut et fin de vie

Le statut se lit sur le transfert (champ status), pas sur chaque fichier individuellement : les fichiers suivent le cycle de vie de leur transfert. Un transfert respecte la fenêtre expires_in_hours et le plafond max_downloads que vous avez fixés à la création ; au-delà, il n'est plus téléchargeable. Pour retirer définitivement un transfert et tous ses fichiers, appelez DELETE /v1/transfers/{id}.