Réponse exemple
GET/v1/billing/snapshotAperçu live du cycle de facturation courant pour le workspace authentifié.Renvoie un instantané informatif (non facturant) du cycle de facturation du workspace. La période courante est calculée du 1er du mois UTC jusqu'à maintenant : usage réel de stockage et d'egress, dépassement (overage) projeté en Go et en EUR si le mois se clôturait à l'instant. L'objet inclut aussi le bilan persisté du mois précédent (montants effectivement facturés, statut de report à Stripe) lorsqu'il existe, et un bloc downgrade_impact si le workspace a changé de plan en cours de mois. Le champ racine object vaut toujours "billing_snapshot".
Sur le plan Free, les dépassements bloquent les uploads et ne sont jamais facturés : le champ current_period.note le signale explicitement et les montants projetés restent à 0.
Authentification
Requiert une clé API valide portant le scope billing:read. Grâce à la hiérarchie de scopes, un token disposant de workspace:billing, workspace:manage ou du wildcard * satisfait également cette exigence. Une session dashboard du propriétaire du workspace passe aussi (scopes *). Sans scope adéquat, l'API répond 403 scope_missing.
Paramètres de requête
Cet endpoint n'accepte aucun paramètre de requête ni corps. Le workspace ciblé et les périodes (mois courant + mois précédent en UTC) sont déduits automatiquement du token d'authentification et de la date du serveur.
Réponse
L'objet current_period expose la period au format AAAA-MM, le plan, les quotas (storage_quota_gb, bandwidth_quota_gb), la consommation arrondie à 4 décimales (storage_used_gb, bandwidth_used_gb), les dépassements (storage_overage_gb, bandwidth_overage_gb), le bloc projected_overage (storage_eur, bandwidth_eur, total_eur arrondis à 2 décimales) et les tarifs unitaires overage_rates (en EUR/Go). previous_period reprend le bilan facturé du mois précédent (storage_amount_eur, bandwidth_amount_eur, total_billed_eur, reported_to_stripe, reported_at) ou vaut null si aucun enregistrement n'existe. downgrade_impact est null sauf rétrogradation en cours de mois, auquel cas il détaille les nouveaux quotas et l'overage recalculé.
| Champ | Type | Description |
|---|---|---|
| object | string | Toujours "billing_snapshot". |
| current_period.period | string | Mois courant au format AAAA-MM (UTC). |
| current_period.plan | string | Plan actuel du workspace (ex. pro, ultra, free). |
| current_period.storage_used_gb | number | Stockage consommé en Go, arrondi à 4 décimales. |
| current_period.bandwidth_used_gb | number | Egress consommé sur le mois en Go, arrondi à 4 décimales. |
| current_period.projected_overage.total_eur | number | Coût total projeté des dépassements en EUR (2 décimales). |
| current_period.overage_rates | object | null | Tarifs unitaires EUR/Go, ou null si le plan n'a pas de produit Stripe associé. |
| current_period.note | string | undefined | Présent uniquement sur le plan Free (dépassements bloquants, non facturés). |
| previous_period | object | null | Bilan facturé du mois précédent, ou null si non disponible. |
| downgrade_impact | object | null | Détail de l'impact d'une rétrogradation mid-month, ou null. |
Erreurs
| Code | Quand | Résolution |
|---|---|---|
| 401 missing_api_key | Aucun en-tête Authorization ni session valide. | Ajouter Authorization: Bearer cof_live_.... |
| 401 invalid_api_key | Préfixe de clé inconnu, clé introuvable ou inactive. | Vérifier la clé ou en générer une nouvelle sur app.coffrify.com/developer. |
| 401 expired_api_key | La clé API a expiré. | Régénérer une clé valide. |
| 403 scope_missing | Le token ne porte pas billing:read (ni un scope plus large). | Émettre une clé avec le scope billing:read, workspace:billing ou workspace:manage. |
| 403 ip_not_allowed | L'IP appelante n'est pas dans la liste autorisée de la clé. | Appeler depuis une IP autorisée ou ajuster l'allowlist. |
| 429 rate_limited | Quota par minute du workspace dépassé (endpoint de lecture). | Respecter l'en-tête Retry-After puis réessayer. |
| 200 (object avec error) | Le workspace est introuvable lors du calcul d'usage. | Réponse { object: "billing_snapshot", error: "workspace_not_found" } : vérifier que le workspace existe. |
| 500 internal_error | Erreur serveur ou RPC de validation en échec. | Réessayer ; si le problème persiste, fournir le X-Request-Id au support. |
Voir aussi
- GET /v1/billing/subscription : état de l'abonnement et plan courant.
GET /v1/quotas: quotas et consommation côté lecture rapide.- GET /v1/billing/usage : détail de la consommation metering.