Liens de partage et expiration

Chaque transfert que vous créez via l'API expose un lien de partage public, le share_url, que vous remettez à vos destinataires pour qu'ils téléchargent les fichiers. Ce lien a une durée de vie, peut être plafonné en nombre de téléchargements, et reste révocable à tout instant. Ce guide détaille le champ share_url, le contrôle de l'expiration via expires_in_hours, le plafond max_downloads, la révocation par suppression, le suivi des téléchargements, ainsi que les bonnes pratiques de diffusion. Tous les appels passent par la base https://api.coffrify.com/v1 avec l'en-tête Authorization: Bearer <clé>.

Obtenir un lien de partage

Le lien naît à la création du transfert. Vous envoyez la liste des fichiers, l'API vous renvoie un objet transfer accompagné d'upload_urls (un lien d'envoi par fichier) et du share_url. Vous téléversez chaque fichier en PUT vers son URL, puis vous communiquez le share_url. Le lien est de la forme https://files.coffrify.com/<short_code>, où short_code est l'identifiant court et lisible du transfert.

import { Coffrify } from "coffrify";
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { transfer, upload_urls, share_url } = await coffrify.transfers.create({
  files: [{ name: "rapport.pdf", size: 482113, mime_type: "application/pdf" }],
  expires_in_hours: 72,
  max_downloads: 3,
  transfer_title: "Rapport trimestriel",
});
 
// Téléversez chaque fichier vers son URL signée
for (const f of upload_urls) {
  await fetch(f.url, {
    method: "PUT",
    headers: f.headers,
    body: fileBufferFor(f.file_id),
  });
}
 
console.log("Lien à partager :", share_url);

La réponse contient l'essentiel pour distribuer le lien. Le short_code se retrouve dans le share_url, et expires_at vous donne l'horodatage exact d'expiration au format ISO 8601.

{
  "transfer": {
    "id": "trf_8K2mQ...",
    "short_code": "r4p9zt",
    "status": "active",
    "expires_at": "2026-06-13T09:00:00.000Z",
    "max_downloads": 3,
    "total_downloads": 0
  },
  "upload_urls": [
    { "file_id": "rapport.pdf", "url": "https://...", "headers": { "Content-Type": "application/octet-stream" } }
  ],
  "share_url": "https://files.coffrify.com/r4p9zt"
}

Définir la durée de vie : expires_in_hours

Le champ expires_in_hours, fourni à la création, fixe la fenêtre pendant laquelle le lien reste téléchargeable. Passé ce délai, le transfert bascule en expiré et toute tentative de téléchargement est refusée. La valeur maximale dépend de votre offre : chaque plan définit une durée de rétention. Si vous omettez expires_in_hours, la valeur par défaut de votre plan s'applique. Vous lisez l'instant précis d'expiration dans le champ expires_at renvoyé par l'API.

Plafonner les téléchargements : max_downloads

Le champ max_downloads borne le nombre total de téléchargements autorisés pour un transfert, toutes personnes confondues. Une fois ce plafond atteint, le lien cesse de servir les fichiers même si la date d'expiration n'est pas dépassée. C'est utile pour un envoi nominatif que vous souhaitez limiter à un ou deux retraits. Le compteur courant est exposé dans total_downloads ; quand total_downloads atteint max_downloads, le transfert est considéré comme épuisé. Laissez max_downloads absent ou nul pour ne pas imposer de plafond.

Prolonger un lien encore actif

Si un destinataire a besoin de plus de temps, vous pouvez repousser l'expiration sans recréer le transfert ni changer le share_url. Appelez l'endpoint d'extension avec soit hours (un nombre d'heures à partir de maintenant), soit until (un horodatage ISO 8601 cible). La nouvelle échéance reste bornée par la rétention de votre plan ; au-delà, l'API renvoie une erreur de validation indiquant le plafond applicable.

$ curl -X POST https://api.coffrify.com/v1/transfers/trf_8K2mQ.../extend \
    -H "Authorization: Bearer $COFFRIFY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "hours": 48 }'
 
{
  "transfer_id": "trf_8K2mQ...",
  "short_code": "r4p9zt",
  "previous_expires_at": "2026-06-13T09:00:00.000Z",
  "new_expires_at": "2026-06-15T09:00:00.000Z",
  "plan": "pro",
  "plan_cap_hours": 720
}

Révoquer un lien : la suppression

Pour couper l'accès immédiatement, supprimez le transfert. La suppression révoque le share_url : les téléchargements en cours et futurs sont refusés. C'est l'action à privilégier si un lien a été diffusé par erreur ou si l'envoi ne doit plus être accessible avant son expiration naturelle.

$ curl -X DELETE https://api.coffrify.com/v1/transfers/trf_8K2mQ... \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"
 
{ "id": "trf_8K2mQ...", "object": "transfer", "deleted": true }

Suivre les téléchargements

Deux niveaux de suivi sont disponibles. Pour un état rapide, lisez le transfert : total_downloads vous indique combien de retraits ont eu lieu, et status plus expires_at vous disent si le lien est encore actif. Pour le détail événement par événement, l'endpoint des téléchargements liste chaque retrait avec son horodatage, son pays, son système et son navigateur.

{
  "object": "list",
  "data": [
    {
      "id": "dl_...",
      "downloaded_at": "2026-06-11T14:22:05.000Z",
      "country_code": "FR",
      "country_name": "France",
      "os": "macOS",
      "browser": "Safari",
      "device_type": "desktop"
    }
  ],
  "has_more": false,
  "total": 1
}

Si vous ne disposez que d'un share_url ou d'un short_code et souhaitez connaître l'état d'un lien (actif, expiré, plafond atteint, supprimé), l'endpoint de résolution renvoie un bloc state synthétique. Il ne révèle que les transferts de votre propre espace de travail.

$ curl -X POST https://api.coffrify.com/v1/transfers/resolve \
    -H "Authorization: Bearer $COFFRIFY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "url": "https://files.coffrify.com/r4p9zt" }'
 
{
  "transfer": { "short_code": "r4p9zt", "status": "active", "total_downloads": 1, "max_downloads": 3 },
  "share_url": "https://files.coffrify.com/r4p9zt",
  "state": { "is_active": true, "is_expired": false, "downloads_capped": false, "is_deleted": false }
}

Bonnes pratiques de diffusion

• Transmettez le share_url par un canal de confiance et, pour les contenus sensibles, ajoutez un mot de passe via le champ password à la création ; communiquez-le séparément du lien.
• Combinez une expiration courte (expires_in_hours) et un plafond serré (max_downloads) pour les envois nominatifs : le lien se referme de lui-même.
• Conservez l'id du transfert de votre côté : c'est lui qui vous permet de prolonger, suivre ou révoquer le lien plus tard.
• Surveillez total_downloads ou les événements de téléchargement pour confirmer la bonne réception avant de laisser le lien expirer.
• En cas de doute sur un lien diffusé, supprimez le transfert sans attendre l'expiration : la révocation est immédiate.
• Utilisez une Idempotency-Key sur la création pour éviter de générer deux transferts (donc deux liens) si une requête est rejouée.