Réponse exemple
GET/v1/billing/recommendationRecommande le plan le mieux dimensionné pour le workspace en fonction de sa consommation réelle sur 30 jours.Cet endpoint mesure la consommation du workspace sur une fenêtre glissante de 30 jours (stockage cumulé des fichiers, bande passante sortante journalière, transferts actifs), puis la compare aux plafonds de chaque plan tarifaire. Il retourne le plan le moins cher dont les quotas de stockage ET de bande passante couvrent l'usage observé, ainsi qu'une direction (upgrade, downgrade ou stay), un delta de coût mensuel et un rationale lisible. Le champ next_tool suggère l'action MCP de suivi pertinente (lien de paiement ou portail de facturation). C'est un endpoint pensé pour les flux d'agents du type "dois-je changer de plan ?".
Authentification
Requiert une clé API valide portant le scope billing:read. Conformément à la hiérarchie de scopes, les scopes plus larges workspace:billing et workspace:manage satisfont également cette exigence, de même que le wildcard *. Le workspace ciblé est déduit du contexte d'authentification (la clé est rattachée à un workspace), il n'a pas à être passé en paramètre.
Paramètres de requête
Cet endpoint n'accepte aucun paramètre de requête ni corps. La fenêtre d'analyse est fixée à 30 jours et le workspace est résolu via la clé API.
Réponse
La réponse est un objet JSON. current_plan est le plan actuel du workspace (en minuscules, free par défaut). usage_30d détaille la consommation : storage_gb et bandwidth_gb (arrondis à 2 décimales) et active_transfers (nombre de transferts au statut active). recommended_plan est le plan recommandé et direction indique s'il faut monter, descendre ou rester. savings_or_cost_delta_eur_per_month est le delta mensuel en euros (positif = surcoût d'un upgrade, négatif = économie d'un downgrade). annual_savings_pct_vs_monthly est le pourcentage d'économie de l'annuel vs le mensuel pour le plan recommandé. rationale est une explication en clair, next_tool suggère l'outil MCP de suivi, et plan_caps liste tous les plans triés par prix mensuel croissant.
| Champ | Type | Description |
|---|---|---|
| workspace_id | string | Identifiant du workspace analysé (issu du contexte d'authentification). |
| current_plan | string | Plan actuel du workspace, en minuscules (free si non défini). |
| usage_30d.storage_gb | number | Stockage cumulé des fichiers en Go, arrondi à 2 décimales. |
| usage_30d.bandwidth_gb | number | Bande passante sortante sur 30 jours en Go, arrondie à 2 décimales. |
| usage_30d.active_transfers | number | Nombre de transferts au statut active. |
| recommended_plan | string | Plan le moins cher couvrant le stockage et la bande passante observés. |
| direction | string | upgrade, downgrade ou stay selon la position du plan recommandé vs l'actuel. |
| savings_or_cost_delta_eur_per_month | number | Delta de coût mensuel en euros (positif = surcoût, négatif = économie). |
| annual_savings_pct_vs_monthly | number | Pourcentage d'économie de la facturation annuelle vs mensuelle pour le plan recommandé. |
| rationale | string | Explication lisible de la recommandation. |
| next_tool | string | null | Outil MCP de suivi suggéré : coffrify_create_checkout_link (upgrade), coffrify_create_billing_portal_link (downgrade) ou null (stay). |
| plan_caps | array | Tous les plans avec leurs plafonds et prix, triés par prix mensuel croissant. |
Erreurs
| Code | Quand | Résolution |
|---|---|---|
| 401 missing_api_key | Aucun en-tête Authorization et aucune session valide. | Fournir un en-tête Authorization: Bearer cof_live_.... |
| 401 invalid_api_key | Clé au préfixe non reconnu, introuvable ou inactive. | Vérifier la clé et son préfixe (cof_live_ / cof_test_, etc.). |
| 401 revoked_api_key | Clé révoquée ou désactivée. | Générer une nouvelle clé depuis app.coffrify.com/developer. |
| 401 expired_api_key | Clé expirée. | Renouveler la clé API. |
| 403 scope_missing | La clé ne porte pas billing:read (ni un scope plus large équivalent). | Émettre une clé avec le scope billing:read, workspace:billing ou workspace:manage. |
| 403 ip_not_allowed | IP appelante hors de l'allowlist de la clé. | Appeler depuis une IP autorisée ou ajuster l'allowlist. |
| 403 forbidden | Session sans workspace résoluble. | S'assurer que l'utilisateur appartient à un workspace ou utiliser une clé API. |
| 429 rate_limited | Quota de requêtes du workspace dépassé (endpoint read) ou max-uses de la clé atteint. | Respecter l'en-tête Retry-After puis réessayer. |
| 500 internal_error | Erreur de validation côté serveur ou indisponibilité du backend. | Réessayer ; consulter request_id pour le support. |
Voir aussi
- GET /v1/billing/subscription — état de l'abonnement et du plan en cours.
- GET /v1/billing/usage — consommation détaillée du workspace (stockage, bande passante, quotas).
- POST /v1/billing/checkout-link — créer un lien de paiement pour exécuter un upgrade recommandé.