Heatmap et top listes

Au-delà du résumé global, COFFRIFY expose trois endpoints d'analyse fine qui répondent à des questions concrètes : quand votre espace est-il actif, quels transferts concentrent l'attention, et quels destinataires reçoivent le plus de fichiers. La heatmap renvoie l'activité ventilée par jour de semaine et par heure, tandis que les top listes classent transferts et destinataires sur une fenêtre temporelle. Toutes ces lectures relèvent du scope analytics:read et s'appellent sur la base https://api.coffrify.com/v1 avec l'en-tête Authorization: Bearer <clé>.

La heatmap d'activité

La heatmap répond à la question « à quels moments de la semaine crée-t-on des transferts dans cet espace ? ». Elle agrège le nombre de transferts créés par tranche horaire sur la fenêtre demandée, et renvoie une grille de 7 jours par 24 heures prête à afficher.

Le seul paramètre est range, qui accepte 7, 30 ou 90 (en jours). Toute autre valeur est ramenée à 30. La réponse contient deux champs : cells, un tableau de 7 lignes (une par jour) de 24 colonnes (une par heure), et total, la somme de toutes les cellules. Dans cells, l'index 0 correspond au lundi et l'index 6 au dimanche ; l'index d'heure va de 0 (minuit) à 23, exprimé dans le fuseau de l'espace de travail.

curl -s 'https://api.coffrify.com/v1/analytics/heatmap?range=30' \
  -H 'Authorization: Bearer cof_live_...'

{
  "cells": [
    [0, 0, 0, 0, 1, 3, 5, 8, 12, 9, 7, 4, 6, 11, 14, 10, 8, 5, 3, 2, 1, 0, 0, 0],
    [0, 0, 0, 0, 0, 2, 4, 9, 13, 10, 6, 5, 7, 12, 15, 11, 9, 6, 4, 2, 1, 1, 0, 0]
  ],
  "total": 1284
}

Top transferts

Cet endpoint classe vos transferts les plus consultés sur une fenêtre glissante, soit par nombre de téléchargements, soit par bande passante consommée. C'est l'outil idéal pour repérer un partage qui circule davantage que prévu ou pour mesurer ce qui pèse réellement sur votre quota de bande passante.

La réponse est une liste (object: "list"). Chaque entrée porte le transfer_id, le short_code, le transfer_title (qui peut être null), le nombre de downloads, la bandwidth_bytes estimée et la date created_at.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { data } = await coffrify.analytics.topTransfers({
  range_days: 30,
  metric: 'bandwidth',
  limit: 10,
});
 
for (const t of data) {
  const gb = (t.bandwidth_bytes / 1e9).toFixed(2);
  console.log(`${t.short_code} - ${t.downloads} téléch. - ${gb} Go`);
}

{
  "object": "list",
  "data": [
    {
      "transfer_id": "trf_8Kq2...",
      "short_code": "a1b2c3",
      "transfer_title": "Dossier juridique Q2",
      "downloads": 142,
      "bandwidth_bytes": 9663676416,
      "created_at": "2026-05-18T09:24:11Z"
    }
  ]
}

Top destinataires

Cet endpoint classe les destinataires de vos transferts par volume reçu sur la fenêtre demandée. Il aide à comprendre vers qui partent le plus de fichiers, utile pour le suivi commercial, la facturation interne par client ou la détection d'un destinataire inhabituellement actif.

Deux paramètres : range_days (entier de 1 à 365, défaut 30) et limit (entier de 1 à 100, défaut 20). La réponse est une liste dont chaque entrée contient l'adresse email, le nombre de transfers_sent, le nombre d'opens, le total de downloads, le taux open_rate (entre 0 et 1) et un booléen in_address_book indiquant si le destinataire figure dans votre carnet d'adresses.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { data } = await coffrify.analytics.topRecipients({
  range_days: 90,
  limit: 15,
});
 
for (const r of data) {
  const pct = Math.round(r.open_rate * 100);
  console.log(`${r.email} - ${r.transfers_sent} envois - ouverture ${pct}%`);
}

{
  "object": "list",
  "data": [
    {
      "email": "client@exemple.fr",
      "transfers_sent": 38,
      "opens": 31,
      "downloads": 54,
      "open_rate": 0.81,
      "in_address_book": true
    }
  ]
}

Cas d'usage combinés

Ces trois lectures se complètent dans un tableau de bord de supervision. Vous pouvez par exemple croiser la heatmap pour caler une fenêtre de maintenance sur les heures les plus calmes, le top transferts en mode bandwidth pour anticiper la consommation du mois, et le top destinataires pour alimenter une revue d'activité par client. Pensez à ajuster range_days selon votre plan : les paliers d'entrée sont plafonnés à 30 jours d'historique tandis que les paliers supérieurs remontent jusqu'à un an.

• Planifier une opération : repérez le creux hebdomadaire via la heatmap (par exemple dimanche entre 2h et 5h) avant une migration ou une coupure.
• Maîtriser les coûts : surveillez chaque semaine top-transfers?metric=bandwidth pour détecter un partage viral avant qu'il ne pèse sur le quota.
• Suivre la relation client : exportez top-recipients sur 90 jours pour identifier vos destinataires récurrents et leur taux d'ouverture.
• Détecter l'anormal : un destinataire qui grimpe brutalement dans le classement, ou un pic horaire inhabituel dans la heatmap, mérite une vérification dans le journal d'audit.