Analytics : vue d'ensemble

L'API Analytics expose en lecture seule l'activité agrégée de votre espace de travail : combien de transferts ont été créés, combien de téléchargements ont eu lieu, quel volume occupe le stockage, et quels destinataires ou transferts ressortent le plus. Un seul appel suffit pour obtenir ce résumé, ce qui en fait le point d'entrée idéal pour alimenter un tableau de bord, un rapport hebdomadaire ou une page d'accueil interne. Tous les chiffres sont calculés sur les données hébergées en UE et restent strictement périmétrés à votre espace.

Cet appel requiert une clé dont le scope inclut analytics:read. Si votre clé ne porte pas ce scope, la réponse est un code 403 avec scope_missing. Pensez à restreindre vos clés au strict nécessaire : une clé qui ne sert qu'à lire des statistiques n'a besoin que de analytics:read.

Récupérer le résumé

Authentifiez la requête avec l'en-tête Authorization: Bearer <clé>. La base de l'API est https://api.coffrify.com/v1. Voici l'appel minimal, côté serveur uniquement (ne jamais exposer une clé cof_live_ dans un navigateur).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const summary = await coffrify.analytics.retrieve();
 
console.log(summary.transfers_count, summary.downloads_count);

La réponse rassemble les compteurs principaux et deux palmarès. Voici un exemple de structure renvoyée.

{
  "transfers_count": 1842,
  "downloads_count": 5310,
  "storage_used": 48213004288,
  "top_recipients": [
    { "email": "client@exemple.fr", "count": 96 },
    { "email": "partenaire@exemple.fr", "count": 74 }
  ],
  "top_transfers": [
    { "id": "trf_9aZ2k", "name": "Dossier juridique", "downloads": 213 },
    { "id": "trf_3bX7m", "name": "Livrables Q2", "downloads": 187 }
  ]
}

Lire les chiffres

Chaque champ répond à une question métier précise. Le tableau ci-dessous résume comment les interpréter.

Un ratio utile à suivre est downloads_count / transfers_count : il indique combien de fois, en moyenne, un transfert est téléchargé. Une valeur basse peut signaler des envois jamais récupérés, une valeur élevée des contenus partagés largement. Les palmarès top_recipients et top_transfers sont triés par fréquence décroissante et permettent de prioriser le suivi commercial ou la rétention de contenus.

Aller plus loin : les vues détaillées

Le résumé donne la photographie d'ensemble. Pour analyser un axe précis, l'API expose des vues spécialisées, toutes accessibles avec le même scope analytics:read. Vous appelez celle qui correspond à votre besoin sans recharger l'intégralité du résumé.

• GET /v1/analytics/geo : répartition géographique de l'activité (par pays ou région)
• GET /v1/analytics/funnel : entonnoir de conversion, de l'envoi au téléchargement
• GET /v1/analytics/heatmap : carte de chaleur temporelle des accès
• GET /v1/analytics/top-transfers : palmarès complet des transferts
• GET /v1/analytics/top-recipients : palmarès complet des destinataires

Là où top_transfers et top_recipients du résumé sont volontairement courts, les endpoints /v1/analytics/top-transfers et /v1/analytics/top-recipients renvoient des listes plus détaillées et paginables par curseur (paramètres limit jusqu'à 100 et cursor, avec has_more et next_cursor dans la réponse).

$ curl https://api.coffrify.com/v1/analytics/geo \
  -H "Authorization: Bearer $COFFRIFY_API_KEY"

Gérer les erreurs

Toutes les erreurs suivent le même format {"error":{"code","message","request_id"}}. Conservez le request_id dans vos journaux : il accélère le diagnostic en cas de demande de support. Les cas les plus courants sur cet endpoint sont une clé invalide (invalid_api_key), un scope manquant (scope_missing) ou un dépassement de débit (rate_limited).

Pour mettre au point votre intégration sans toucher à des données réelles, utilisez une clé cof_test_ ou une clé cof_sandbox_ (environnement isolé valable 24 h). Une fois la lecture validée, basculez sur votre clé cof_live_ restreinte au seul scope analytics:read.