Se connecterCommencer gratuitement
Référence APIRécupérer la timeline d'un transfert
GET/v1/transfers/{id}/timeline

Récupérer la timeline d'un transfert

Renvoie la chronologie agrégée et triée de tous les événements survenus sur un transfert (création, scans, téléchargements, liens magiques, webhooks, audit).

2 min de lectureTélécharger en PDF

Réponse exemple

{
  "data": [
    {
      "at": "2026-06-05T14:32:10.000Z",
      "kind": "download",
      "summary": "Downloaded from France (Chrome) - 12.45 MB",
      "metadata": {
        "ip": "92.184.105.12",
        "os": "macOS",
        "browser": "Chrome",
        "country": "FR"
      }
    },
    {
      "at": "2026-06-05T14:30:02.000Z",
      "kind": "webhook_delivery",
      "summary": "Webhook fired: transfer.downloaded → 200 (delivered)",
      "metadata": {
        "status": "delivered",
        "event_type": "transfer.downloaded",
        "delivery_id": "d4e5f6a7-1234-5678-9abc-def012345678",
        "status_code": 200
      }
    },
    {
      "at": "2026-06-05T11:05:44.000Z",
      "kind": "magic_link_used",
      "summary": "Magic link used (8f3a2b9c1d4e…)",
      "metadata": {
        "token_prefix": "8f3a2b9c1d4e…"
      }
    },
    {
      "at": "2026-06-05T10:58:00.000Z",
      "kind": "magic_link_created",
      "summary": "Magic link issued (8f3a2b9c1d4e…), expires 2026-06-12T10:58:00.000Z",
      "metadata": {
        "expires_at": "2026-06-12T10:58:00.000Z",
        "token_prefix": "8f3a2b9c1d4e…"
      }
    },
    {
      "at": "2026-06-05T09:00:00.000Z",
      "kind": "created",
      "summary": "Transfer k9XmP2 created (\"Contrat de cession - Projet Atlas\")",
      "metadata": {
        "status": "active",
        "expires_at": "2026-06-19T09:00:00.000Z",
        "encryption_mode": "e2e",
        "is_password_protected": true
      }
    }
  ],
  "object": "list",
  "summary": {
    "total_events": 11,
    "downloads_count": 7,
    "last_download_at": "2026-06-05T14:32:10.000Z",
    "magic_links_total": 2,
    "magic_links_active": 1,
    "webhook_fires_related": 2
  },
  "transfer": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Contrat de cession - Projet Atlas",
    "status": "active",
    "created_at": "2026-06-05T09:00:00.000Z",
    "expires_at": "2026-06-19T09:00:00.000Z",
    "short_code": "k9XmP2",
    "scan_status": "clean",
    "total_downloads": 7
  }
}
GET/v1/transfers/{id}/timelineChronologie agrégée et triée par ordre décroissant de tous les événements d'un transfert.

Renvoie la timeline complète d'un transfert : un flux chronologique unique qui agrège, à partir de plusieurs sources internes, tout ce qui s'est produit sur le transfert. Sont consolidés : la création, les téléchargements (avec IP, pays, navigateur, OS et volume), les liens magiques émis et utilisés, les livraisons de webhooks qui mentionnent ce transfert (filtrées par transfer_id ou short_code présents dans le payload), ainsi que les événements d'audit dont la ressource correspond au transfert (changements de mot de passe et envois d'e-mails sont reclassés à partir de l'action d'audit). Tous les événements sont fusionnés puis triés par horodatage décroissant (le plus récent en premier). L'endpoint est classé expensive côté quota car il déclenche plusieurs requêtes et un appel d'audit en parallèle.

Authentification

Requiert une clé API valide possédant le scope transfers:read. Le transfert est résolu dans le périmètre du workspace associé à la clé (workspace_id) : une clé d'un autre workspace reçoit 404 not_found, jamais les données d'un transfert tiers.

Paramètres de requête

ParamètreTypeRequisDescription
idstring (path)OuiIdentifiant (UUID) du transfert dont on veut la timeline. Fourni dans le chemin de l'URL.limit
ParamètreTypeRequisDescription
limitinteger (query)NonNombre maximal d'événements renvoyés dans data. Défaut 200, borné entre 1 et 1000. Les téléchargements sont par ailleurs récupérés jusqu'à un plafond interne de 500.

Réponse

La réponse est un objet contenant trois sections. `transfer` rappelle l'état courant du transfert : id, short_code, title, status, scan_status, total_downloads, expires_at, created_at. `summary` synthétise l'activité : total_events, downloads_count, magic_links_total, magic_links_active (liens non utilisés et non expirés), webhook_fires_related et last_download_at. Enfin `data` (object = list) est le tableau d'événements triés, chacun portant at (horodatage ISO), kind, summary (texte lisible) et un metadata optionnel propre au type d'événement.

kindSignificationMétadonnées notables
createdCréation du transfertstatus, encryption_mode, is_password_protected, expires_at
downloadTéléchargement enregistréip, country, os, browser
magic_link_createdLien magique émistoken_prefix, expires_at
magic_link_usedLien magique consommétoken_prefix
webhook_deliveryLivraison de webhook liée au transfertdelivery_id, event_type, status, status_code
password_changeChangement de mot de passe (issu de l'audit)actor, ip, action
email_sentEnvoi d'e-mail de partage (issu de l'audit)actor, ip, action
auditAutre événement d'audit sur le transfertactor, ip, action

Erreurs

CodeQuandRésolution
401 missing_api_keyEn-tête Authorization absentEnvoyer Authorization: Bearer cof_live_....
401 invalid_api_keyClé invalide, mal préfixée ou introuvableVérifier le format et la validité de la clé.
403 scope_missingLa clé n'a pas le scope transfers:readÉmettre une clé incluant transfers:read.
404 not_foundTransfert inexistant ou hors du workspace de la cléVérifier l'id et que le transfert appartient bien au workspace.
429 rate_limitedQuota par minute dépassé (endpoint expensive)Respecter Retry-After et X-RateLimit-Reset avant de réessayer.
500 internal_errorErreur lors de la lecture du transfertRéessayer ; conserver le request_id renvoyé pour le support.

Voir aussi