Plafonds et expiration

Un transfert qui reste accessible indéfiniment est un risque inutile. Coffrify vous donne deux leviers complémentaires pour borner la durée de vie de chaque partage : max_downloads, qui limite le nombre de téléchargements, et expires_in_hours, qui fixe une date d'expiration. Vous les définissez à la création du transfert, le lien se bloque automatiquement dès que l'une des deux limites est atteinte, et les fichiers finissent par être purgés du stockage. Cette page explique le comportement exact de ces plafonds, ce qui se passe à l'épuisement, et les bonnes pratiques pour calibrer la durée de vie selon la sensibilité de vos données.

Deux leviers : nombre de téléchargements et expiration

À la création d'un transfert via POST /v1/transfers, vous pouvez fournir deux champs optionnels qui pilotent sa durée de vie. Ils sont indépendants : vous pouvez n'en utiliser qu'un, les deux, ou aucun. Quand les deux sont présents, c'est la première limite atteinte qui ferme le lien, qu'il s'agisse du quota de téléchargements ou de la date d'expiration.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const transfer = await coffrify.transfers.create({
  files: [{ name: 'offre.pdf', size: 482113, mime_type: 'application/pdf' }],
  transfer_title: 'Offre commerciale',
  expires_in_hours: 24,
  max_downloads: 3,
});
 
console.log('Lien :', transfer.share_url);
console.log('Expire le :', transfer.expires_at);

La réponse contient le bloc transfer avec sa date d'expiration calculée dans expires_at, ainsi que les upload_urls à utiliser en PUT pour téléverser vos fichiers. Conservez transfer.id et transfer.short_code : ils vous permettront de suivre l'état du transfert et son décompte de téléchargements.

{
  "transfer": {
    "id": "tr_9fK2mQ",
    "short_code": "a8B3xZ",
    "status": "active",
    "share_url": "https://files.coffrify.com/a8B3xZ",
    "expires_at": "2026-06-11T14:00:00Z",
    "scan_status": "pending"
  },
  "upload_urls": [
    { "file_id": "file_abc123", "url": "https://...", "headers": { "Content-Type": "application/pdf" } }
  ],
  "share_url": "https://files.coffrify.com/a8B3xZ"
}

Ce qui se passe à l'épuisement

Dès qu'une limite est atteinte, le lieu de partage cesse de servir les fichiers. Le passage se fait en deux temps : d'abord le blocage du lien, immédiat, puis la purge des fichiers du stockage, qui rend la suppression définitive.

• Quota de téléchargements atteint : une fois max_downloads consommé, toute nouvelle tentative de téléchargement est refusée. Le lien existe toujours mais ne délivre plus aucun fichier.
• Expiration atteinte : passé expires_at, le transfert bascule en expiré et le lien ne donne plus accès au contenu, même si le quota de téléchargements n'a pas été épuisé.
• Purge des fichiers : après blocage, les fichiers chiffrés sont purgés du stockage. La récupération devient impossible, y compris pour vous : il faut alors recréer un transfert.
• Suppression manuelle : vous pouvez toujours fermer un lien avant ses limites avec DELETE /v1/transfers/{id}, ce qui déclenche le même processus de purge.

Suivre l'état et le décompte

Vous n'avez pas besoin de deviner où en est un transfert : un appel GET /v1/transfers/{id} renvoie son status et sa date d'expiration. Pour réagir en temps réel, abonnez-vous aux webhooks transfer.downloaded (à chaque téléchargement) et transfer.expired (au franchissement de l'expiration), afin de relancer un partage ou prévenir un destinataire automatiquement.

const transfer = await coffrify.transfers.get('tr_9fK2mQ');
 
if (transfer.status === 'expired') {
  console.log('Lien expiré, fichiers purgés.');
} else {
  console.log('Encore actif, expire le', transfer.expires_at);
}

Bonnes pratiques

• Calez la durée sur la sensibilité : plus les données sont confidentielles, plus expires_in_hours doit être court. Pour un document très sensible, quelques heures suffisent souvent.
• Associez un quota au nombre réel de destinataires : si un seul destinataire est attendu, fixez max_downloads à 1 (ou 2 pour absorber un nouvel essai) plutôt que de laisser le lien ouvert.
• Préférez l'expiration courte au lien permanent : un transfert à durée de vie limitée se purge tout seul, ce qui réduit le risque qu'un ancien lien circule encore.
• Surveillez via webhooks : écoutez transfer.downloaded et transfer.expired pour automatiser vos relances et vos audits, plutôt que d'interroger l'API en boucle.
• Ne réutilisez pas un lien expiré : recréez un transfert. Tenter de prolonger un lien dont les fichiers sont purgés n'est pas possible.

En résumé, max_downloads et expires_in_hours vous laissent décider précisément combien de fois et pendant combien de temps un partage reste vivant. La première limite atteinte ferme le lien, puis les fichiers sont purgés sans retour possible. Définissez ces plafonds dès la création, suivez l'état via GET ou les webhooks, et calibrez la durée de vie au plus juste pour chaque transfert.