Cycle de vie d'un transfert

Un transfert Coffrify n'est pas un objet figé : il naît, vit le temps que vous lui accordez, puis disparaît. Comprendre ce cycle de vie vous permet d'anticiper précisément à quel moment un lien cesse de fonctionner, quand les fichiers sont purgés du stockage, et quels évènements votre intégration reçoit à chaque étape. Cette vue d'ensemble décrit les états possibles d'un transfert, les transitions automatiques (notamment l'expiration), la suppression manuelle, et les webhooks émis tout au long du parcours.

Les états d'un transfert

Chaque transfert porte un champ status qui reflète sa position dans le cycle de vie. Vous le retrouvez dans la réponse de création, dans GET /v1/transfers et dans GET /v1/transfers/{id}. Voici les valeurs possibles :

Un transfert fraîchement créé passe à active dès que vos fichiers sont téléversés via les upload_urls. Tant qu'il est active, il reste accessible via son share_url, dans la limite de sa date d'expiration et de son éventuel plafond de téléchargements (max_downloads).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { data } = await coffrify.transfers.list({ status: 'active', limit: 50 });
for (const t of data) {
  console.log(t.short_code, t.status, t.expires_at);
}

Ce qui se passe à l'expiration

Vous fixez la durée de vie d'un transfert à la création avec expires_in_hours. Le champ expires_at (horodatage ISO 8601) vous donne la date exacte. Une tâche planifiée s'exécute chaque heure côté Coffrify : elle bascule automatiquement en expired tout transfert encore active dont l'expires_at est dépassé. La transition est atomique et émise exactement une fois, donc vous ne recevez jamais de doublon de l'évènement d'expiration.

Concrètement, à l'expiration :

• Le status passe de active à expired.
• Le lien de partage est bloqué : toute tentative de téléchargement échoue.
• Les fichiers sont purgés du stockage. L'expiration est définitive et irréversible côté contenu.
• L'évènement transfer.expired est émis vers vos webhooks abonnés.

Prolonger un transfert avant l'échéance

Tant qu'un transfert n'est pas supprimé, vous pouvez repousser son expiration et le maintenir active. Passez soit un nombre d'heures, soit une date cible ISO 8601. La nouvelle échéance est bornée par la rétention maximale de votre offre.

const result = await coffrify.transfers.extend('tr_123', { hours: 48 });
console.log(result.previous_expires_at, '→', result.new_expires_at);

La réponse renvoie previous_expires_at, new_expires_at et plan_cap_hours, le plafond appliqué par votre offre. Une date au-delà de ce plafond est refusée par une erreur de validation.

Supprimer un transfert manuellement

Pour couper l'accès immédiatement, sans attendre l'expiration, supprimez le transfert. Le lien est aussitôt bloqué et le transfert passe à l'état supprimé.

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

La suppression déclenche l'évènement transfer.deleted. Comme pour l'expiration, l'opération est définitive : les fichiers ne sont plus servis et le share_url cesse de fonctionner.

Les évènements du cycle de vie

Abonnez un webhook (POST /v1/webhooks) pour suivre un transfert en temps réel. Les évènements clés du cycle de vie sont les suivants. Chaque charge utile inclut au minimum transfer_id et short_code.

D'autres évènements jalonnent la vie d'un transfert selon vos options : l'analyse antivirus (transfer.scanned, puis transfer.scan_clean ou transfer.scan_infected), l'atteinte du plafond de téléchargements (transfer.limit_reached), un mot de passe erroné (transfer.password_failed) ou un accès refusé par règle géographique (transfer.geo_blocked). La liste complète et à jour des types d'évènements est exposée publiquement sur GET /v1/webhooks/events, sans authentification.

Récapitulatif

Un transfert démarre active, reste accessible jusqu'à son expires_at ou jusqu'à atteindre son plafond de téléchargements, puis bascule automatiquement en expired avec purge des fichiers. Vous pouvez prolonger sa durée de vie avec /extend tant qu'il existe, ou couper l'accès immédiatement avec DELETE. À chaque étape, les webhooks transfer.created, transfer.downloaded, transfer.expired et transfer.deleted tiennent votre intégration informée, vous laissant le contrôle complet du parcours sans avoir à interroger l'API en boucle.