Analyser les top transferts et destinataires avec l'API analytics

Interrogez les trois endpoints d'analytics Coffrify pour obtenir un résumé d'usage, les transferts les plus téléchargés et les destinataires les plus actifs sur votre workspace.

Télécharger en PDF

L'API analytics de Coffrify expose trois endpoints complémentaires : un résumé d'usage global du workspace (GET /v1/analytics), le classement des transferts par téléchargements ou bande passante (GET /v1/analytics/top-transfers) et le classement des destinataires par volume d'envois (GET /v1/analytics/top-recipients). Ces endpoints sont en lecture seule, classés comme expensive dans le gestionnaire de rate-limit, et renvoient des données agrégées prêtes à injecter dans vos tableaux de bord ou vos alertes automatisées.

GET/v1/analyticsRésumé d'usage du workspace : compteurs de transferts, stockage, bande passante sur la plage demandée et top 5 par téléchargements.GET/v1/analytics/top-transfersClassement des N meilleurs transferts triés par téléchargements ou bande passante estimée (taille des fichiers × téléchargements).GET/v1/analytics/top-recipientsClassement des destinataires les plus actifs : nombre de transferts reçus, téléchargements et taux d'ouverture.

Authentification

Ces trois endpoints requièrent le scope analytics:read. Transmettez votre clé API en en-tête Authorization: Bearer <clé>. En mode test utilisez un préfixe cof_test_…, en production cof_live_…. Les environnements bac à sable utilisent cof_sandbox_….

Paramètres de requête

Les trois endpoints partagent quelques paramètres (plage de dates, taille du classement). Le tableau ci-dessous indique, pour chaque paramètre, les endpoints concernés et les valeurs par défaut.

Paramètre	Endpoint(s)	Type	Défaut	Description
`range_days`	tous	entier	`30`	Plage historique en jours. Plans Free et Pro : max 30 jours. Plans Ultra et Entreprise : max 365 jours. Valeur minimale : 1.
`metric`	`/top-transfers`	string	`downloads`	Critère de tri : `downloads` (téléchargements) ou `bandwidth` (bande passante estimée).
`limit`	`/top-transfers`, `/top-recipients`	entier	`20`	Nombre de résultats à retourner. Minimum 1, maximum 100.

Les exemples ci-dessous appellent successivement le résumé, le top transferts et le top destinataires. Choisissez votre langage.

# Résumé workspace (30 derniers jours)
curl -G https://api.coffrify.com/v1/analytics \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "range_days=30"
 
# Top 10 transferts par bande passante sur 7 jours
curl -G https://api.coffrify.com/v1/analytics/top-transfers \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "range_days=7" \
  --data-urlencode "metric=bandwidth" \
  --data-urlencode "limit=10"
 
# Top 5 destinataires sur 30 jours
curl -G https://api.coffrify.com/v1/analytics/top-recipients \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "range_days=30" \
  --data-urlencode "limit=5"

Réponses

Chaque endpoint retourne un objet JSON avec des champs fixes. Voici les trois formes de réponse réelles.

// GET /v1/analytics
{
  "workspace": {
    "id": "ws_01hx...",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "pro"
  },
  "range": {
    "since": "2026-05-07T10:00:00.000Z",
    "days": 30,
    "plan_max_days": 30
  },
  "counts": {
    "transfers_total": 214,
    "transfers_active": 87,
    "transfers_expired": 62,
    "downloads_in_range": 1430
  },
  "storage_bytes": 4831838208,
  "bandwidth_bytes_in_range": 12884901888,
  "bandwidth_daily": [
    { "day": "2026-05-07", "bytes_egress": 209715200 },
    { "day": "2026-05-08", "bytes_egress": 524288000 }
  ],
  "top_transfers": [
    {
      "id": "tr_01hy...",
      "short_code": "ab3xz",
      "transfer_title": "Rapport Q1 2026",
      "total_downloads": 312,
      "created_at": "2026-04-02T08:14:00.000Z"
    }
  ]
}

// GET /v1/analytics/top-transfers
{
  "object": "list",
  "data": [
    {
      "transfer_id": "tr_01hy...",
      "short_code": "ab3xz",
      "transfer_title": "Rapport Q1 2026",
      "downloads": 312,
      "bandwidth_bytes": 9932736000,
      "created_at": "2026-04-02T08:14:00.000Z"
    },
    {
      "transfer_id": "tr_01hz...",
      "short_code": "kp7mn",
      "transfer_title": "Contrat NDA Partenaire B",
      "downloads": 54,
      "bandwidth_bytes": 278528000,
      "created_at": "2026-05-15T14:30:00.000Z"
    }
  ]
}

// GET /v1/analytics/top-recipients
{
  "object": "list",
  "data": [
    {
      "email": "alice@exemple.com",
      "transfers_sent": 18,
      "opens": 14,
      "downloads": 97,
      "open_rate": 0.777,
      "in_address_book": true
    },
    {
      "email": "bob@partenaire.fr",
      "transfers_sent": 11,
      "opens": 9,
      "downloads": 42,
      "open_rate": 0.818,
      "in_address_book": false
    }
  ]
}

Erreurs

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

HTTP	Code d'erreur	Quand cela arrive	Résolution
401	`missing_api_key`	Aucune clé fournie dans l'en-tête `Authorization`.	Ajoutez `Authorization: Bearer cof_live_…` à chaque requête.
401	`invalid_api_key`	Clé malformée ou inexistante.	Vérifiez le préfixe (`cof_test_…`, `cof_live_…`, `cof_sandbox_…`) et les caractères de la clé.
401	`expired_api_key`	La clé a dépassé sa date d'expiration configurée.	Générez une nouvelle clé dans le console Coffrify.
401	`revoked_api_key`	La clé a été révoquée manuellement.	Créez une nouvelle clé et mettez à jour vos intégrations.
403	`scope_missing`	La clé ne dispose pas du scope `analytics:read`.	Éditez la clé ou créez-en une nouvelle en cochant le scope `analytics:read`.
403	`ip_not_allowed`	L'adresse IP source ne figure pas dans la liste blanche de la clé.	Ajoutez l'IP de votre serveur dans les restrictions de la clé.
429	`rate_limited`	Quota de la classe `expensive` dépassé pour ce workspace.	Attendez la valeur indiquée dans l'en-tête `Retry-After`, puis relancez.
500	`internal_error`	Erreur interne (ex. RPC Supabase indisponible).	Réessayez avec un backoff exponentiel. Contactez le support si l'erreur persiste.

Bonnes pratiques

1. Respectez la classe `expensive` : les trois endpoints sont soumis au quota de la classe expensive, plus restrictif que les appels en lecture standard. Mutualisez les appels en parallèle (Promise.all, asyncio.gather) plutôt que de les enchaîner séquentiellement. 2. Utilisez `range_days` de manière ciblée : sur les plans Free et Pro, la plage maximale est de 30 jours. Inutile de demander 90 jours : l'API renverra toujours 30 jours. Les plans Ultra et Entreprise voient jusqu'à 365 jours. 3. Triez par `bandwidth` pour identifier les gros volumes : le champ bandwidth_bytes de /top-transfers est une estimation (taille × téléchargements) ; il reste fiable pour identifier les transferts les plus consommateurs de bande passante sans requête supplémentaire. 4. Exploitez `bandwidth_daily` : le tableau bandwidth_daily de /v1/analytics est idéal pour alimenter un graphique de tendance. Chaque entrée contient un day (YYYY-MM-DD) et bytes_egress. 5. Pagination et `limit` : /top-transfers et /top-recipients acceptent limit jusqu'à 100. Pour un tableau de bord, 10 à 20 résultats suffisent généralement et réduisent la charge réseau.

Voir aussi

Référence GET /v1/analytics
Référence GET /v1/analytics/top-transfers
Référence GET /v1/analytics/top-recipients
Créer un transfert et suivre ses téléchargements
Exporter les logs d'audit
Scopes et permissions des clés API
Rate limits de l'API Coffrify

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→