Usage et quotas

Cette page explique comment lire la consommation d'un espace de travail Coffrify et interroger ses quotas via l'API REST v1. Vous y trouverez l'appel récapitulatif GET /v1/billing/usage, les quotas détaillés (stockage, bande passante, débit), une vérification synthétique GET /v1/quotas/check, et les évènements de webhook qui vous préviennent avant qu'un seuil ne soit atteint. Toutes les requêtes s'authentifient avec un en-tête Authorization: Bearer <clé> et la lecture nécessite les portées billing:read pour la facturation et analytics:read côté usage applicatif.

Vue d'ensemble de la consommation

L'appel GET /v1/billing/usage renvoie un instantané de la consommation du cycle de facturation en cours : volume stocké, bande passante consommée, nombre de transferts et de téléchargements, ainsi que les limites associées à votre offre. C'est le point d'entrée recommandé pour afficher une jauge de consommation dans votre propre interface.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const usage = await coffrify.billing.usage.retrieve();
console.log(usage.storage_used, usage.storage_limit);
console.log(usage.bandwidth_used, usage.bandwidth_limit);

La réponse expose les compteurs du cycle (consommé et limite) ainsi que la période couverte. Adaptez l'affichage en calculant un pourcentage consommé / limite pour matérialiser la marge restante.

{
  "object": "billing.usage",
  "period_start": "2026-06-01T00:00:00Z",
  "period_end": "2026-06-30T23:59:59Z",
  "storage_used": 48318382080,
  "storage_limit": 107374182400,
  "bandwidth_used": 12884901888,
  "bandwidth_limit": 268435456000,
  "transfers_count": 1342,
  "downloads_count": 8907
}

Les quotas en détail

Lorsque vous avez besoin d'une seule dimension, interrogez le quota correspondant. Chaque endpoint renvoie la valeur consommée, la limite et la marge restante pour ce poste précis, ce qui évite de récupérer le récapitulatif complet.

const storage = await coffrify.quotas.storage.retrieve();
 
if (storage.used / storage.limit > 0.9) {
  console.warn('Stockage proche de la limite :', storage.remaining, 'octets restants');
}

{
  "object": "quota",
  "resource": "storage",
  "used": 48318382080,
  "limit": 107374182400,
  "remaining": 59055800320,
  "unit": "bytes"
}

Vérifier tous les quotas d'un coup

Avant une opération volumineuse (par exemple un import massif ou l'ouverture d'un coffre partagé largement), appelez GET /v1/quotas/check pour obtenir l'état consolidé de toutes les dimensions. La réponse signale d'un coup si une limite est dépassée ou sur le point de l'être, ce qui vous permet de bloquer ou d'avertir côté application avant même de lancer le traitement.

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

Anticiper les dépassements par webhook

Plutôt que d'interroger les quotas en boucle, abonnez-vous aux évènements de webhook. Coffrify émet workspace.usage_limit_warning lorsqu'un seuil d'alerte est franchi (par exemple à l'approche de la limite), puis workspace.usage_limit_reached une fois la limite atteinte. Vous recevez aussi workspace.plan_changed quand l'offre change. Réagissez à ces évènements pour notifier vos utilisateurs, déclencher un passage à l'offre supérieure ou suspendre les nouveaux envois.

{
  "type": "workspace.usage_limit_warning",
  "data": {
    "resource": "storage",
    "used": 96636764160,
    "limit": 107374182400,
    "usage_ratio": 0.9
  }
}