Mesurer le taux de conversion et la géolocalisation des téléchargements

L'API Coffrify expose trois endpoints d'observabilité complémentaires : GET /v1/analytics/funnel calcule l'entonnoir créé → uploadé → ouvert → téléchargé avec les taux de conversion et les points de chute ; GET /v1/analytics/geo regroupe les téléchargements par pays et par ville sur la fenêtre demandée ; GET /v1/analytics/heatmap renvoie une matrice 7 jours × 24 heures des transferts créés, idéale pour détecter vos pics d'usage. Ces trois endpoints partagent le même scope, le même mécanisme d'authentification et le même format de réponse JSON.

Authentification

Ces trois endpoints requièrent le scope analytics:read. Transmettez votre clé API dans l'en-tête Authorization: Bearer <clé>. Les clés de test commencent par cof_test_…, les clés de production par cof_live_…, et les clés sandbox par cof_sandbox_…. Toute requête sans clé valide ou sans le scope adéquat reçoit une réponse 401 avec le code d'erreur missing_api_key ou scope_missing.

Paramètres de requête

Les trois endpoints partagent une fenêtre temporelle (range ou days) avec des bornes propres. Le tableau ci-dessous les détaille par endpoint.

Les exemples ci-dessous appellent l'entonnoir, la répartition géographique, puis la heatmap. Choisissez votre langage.

# Entonnoir sur 7 jours
curl -s "https://api.coffrify.com/api/v1/analytics/funnel?range_days=7" \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# Géolocalisation sur 30 jours
curl -s "https://api.coffrify.com/api/v1/analytics/geo?range_days=30" \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# Heatmap sur 90 jours
curl -s "https://api.coffrify.com/api/v1/analytics/heatmap?range=90" \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"

Réponses

Chaque endpoint renvoie une structure dédiée : l'entonnoir liste les étapes et leurs taux, la géo classe pays et villes, la heatmap renvoie une matrice 7×24. Les onglets ci-dessous montrent les trois.

// GET /v1/analytics/funnel?range_days=7
{
  "range_days": 7,
  "stages": [
    { "stage": "created",    "count": 42, "conversion_pct": 100 },
    { "stage": "uploaded",   "count": 42, "conversion_pct": 100 },
    { "stage": "opened",     "count": 31, "conversion_pct": 74 },
    { "stage": "downloaded", "count": 31, "conversion_pct": 74 }
  ],
  "dropoff_points": [
    { "from": "created",  "to": "uploaded",   "lost": 0,  "reason_hint": null },
    { "from": "uploaded", "to": "opened",     "lost": 11, "reason_hint": "email pas recu / pas clique - verifier deliverability" },
    { "from": "opened",   "to": "downloaded", "lost": 0,  "reason_hint": null }
  ]
}

Erreurs

Ces endpoints relèvent de la classe expensive (quota dédié). Au-delà de l'authentification, surveillez le 429. Le tableau ci-dessous détaille les cas.

Voir aussi

• Vue d'ensemble des métriques workspace
• Top transferts par téléchargements
• Top destinataires
• Logs de téléchargement et audit trail
• Webhooks d'événements analytics
• Authentification et scopes de l'API Coffrify