Entonnoir de téléchargement

Un transfert n'est utile que s'il est réellement récupéré. Entre l'envoi et le téléchargement, plusieurs étapes peuvent faire décrocher un destinataire : l'e-mail n'arrive pas, le lien n'est jamais ouvert, le mot de passe bloque, une restriction géographique s'applique. L'endpoint GET /v1/analytics/funnel reconstitue cet entonnoir pour votre espace de travail et chiffre, étape par étape, combien de transferts avancent et combien se perdent. Vous obtenez à la fois les volumes, les taux de conversion et des indices sur les points d'abandon, de quoi diagnostiquer un problème de diffusion sans interroger vos destinataires un par un.

Les quatre étapes

L'entonnoir suit quatre étapes ordonnées, de la création du transfert jusqu'au téléchargement effectif par un destinataire. Chaque étape porte un volume (count) et un taux de conversion (conversion_pct) calculé par rapport à l'étape précédente, la première étant à 100 %.

Requête

L'appel exige le scope analytics:read sur votre clé. Un seul paramètre de requête est accepté : range_days, la fenêtre d'analyse en jours. Sa valeur va de 1 à 365 (les valeurs hors plage sont ramenées dans ces bornes) et vaut 30 par défaut. C'est une lecture seule : aucun en-tête Idempotency-Key n'est requis.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const funnel = await coffrify.analytics.conversionFunnel({ range_days: 30 });
 
for (const s of funnel.stages) {
  console.log(`${s.stage.padEnd(11)} ${s.count}\t${s.conversion_pct}%`);
}

Réponse

La réponse contient la fenêtre appliquée (range_days), le tableau stages des quatre étapes, et dropoff_points, la liste des transitions d'une étape à la suivante avec le nombre de transferts perdus (lost) et un indice de cause (reason_hint, ou null si la perte reste normale).

{
  "range_days": 30,
  "stages": [
    { "stage": "created",    "count": 1247, "conversion_pct": 100 },
    { "stage": "uploaded",   "count": 1247, "conversion_pct": 100 },
    { "stage": "opened",     "count": 921,  "conversion_pct": 74 },
    { "stage": "downloaded", "count": 812,  "conversion_pct": 88 }
  ],
  "dropoff_points": [
    { "from": "created",  "to": "uploaded",   "lost": 0,   "reason_hint": null },
    { "from": "uploaded", "to": "opened",     "lost": 326, "reason_hint": "email pas recu / pas clique - verifier deliverability" },
    { "from": "opened",   "to": "downloaded", "lost": 109, "reason_hint": null }
  ]
}

Comprendre les abandons

Le champ reason_hint n'apparaît que lorsqu'une perte sort de l'ordinaire ; il oriente le diagnostic vers la bonne cause. À partir des trois transitions, vous savez immédiatement où agir.

• created → uploaded : une perte ici signale des transferts restés en brouillon, fichiers jamais déposés. Vérifiez le déroulé de l'envoi côté client.
• uploaded → opened : c'est l'étape de diffusion. Une perte forte pointe vers un e-mail non reçu ou non cliqué : contrôlez la délivrabilité, l'objet du message et le bon destinataire.
• opened → downloaded : le lien est ouvert mais le fichier n'est pas récupéré. Un mot de passe, une restriction géographique ou une étape de vérification peuvent bloquer le destinataire au dernier moment.

Construire un suivi

L'exemple suivant calcule un taux de bout en bout (transferts téléchargés rapportés aux transferts créés) et met en avant la première transition qui dépasse un seuil d'abandon, pour alimenter un tableau de bord ou une alerte interne.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { stages, dropoff_points } = await coffrify.analytics.conversionFunnel({ range_days: 30 });
 
const created = stages.find(s => s.stage === 'created')?.count ?? 0;
const downloaded = stages.find(s => s.stage === 'downloaded')?.count ?? 0;
const endToEnd = created ? Math.round((downloaded / created) * 100) : 0;
console.log(`Taux global creation -> telechargement : ${endToEnd}%`);
 
const worst = dropoff_points
  .filter(p => p.reason_hint)
  .sort((a, b) => b.lost - a.lost)[0];
 
if (worst) {
  console.log(`Plus gros abandon : ${worst.from} -> ${worst.to} (${worst.lost} perdus)`);
  console.log(`Piste : ${worst.reason_hint}`);
}

Erreurs

Si la clé ne porte pas le scope analytics:read, l'API répond 403 avec le code scope_missing. Comme partout, le corps d'erreur suit le format standard avec un request_id à citer en cas de support.

{
  "error": {
    "code": "scope_missing",
    "message": "This API key is missing the required scope: analytics:read",
    "request_id": "req_01J6..."
  }
}