Obtenir un snapshot d'abonnement et une recommandation de plan

Deux endpoints complémentaires permettent de piloter la facturation de votre workspace. `GET /v1/billing/snapshot` retourne un aperçu live du cycle de facturation courant : usage réel (stockage et bande passante), overage projeté en euros, bilan du mois précédent et, le cas échéant, l'impact d'une rétrogradation de plan en cours de mois. `GET /v1/billing/recommendation` analyse 30 jours d'historique et détermine le plan le moins coûteux qui couvre votre consommation, avec le delta mensuel et la prochaine action recommandée. Le endpoint diagnostics `GET /v1/diagnostics/plan-recommendation` propose la même logique avec une fenêtre configurable (range_days) et inclut la contrainte max_active_transfers. Les trois endpoints partagent le même scope et sont conçus pour des flux automatisés (agents MCP, dashboards, alertes).

Authentification

Les trois endpoints requièrent une clé API avec le scope billing:read. Ce scope est disponible sur les plans Pro et Ultra. Transmettez la clé dans l'en-tête HTTP Authorization au format Bearer : Authorization: Bearer cof_live_…. En environnement de test, utilisez le préfixe cof_test_…. Les clés sandbox (cof_sandbox_…) ne peuvent pas accéder aux données de facturation réelles.

Paramètres de requête

La variante diagnostics accepte une fenêtre configurable et une contrainte sur les transferts actifs. Le tableau ci-dessous détaille les paramètres par endpoint.

Exemples d'appel

Les exemples ci-dessous récupèrent le snapshot de facturation, puis la recommandation de plan. Choisissez votre langage.

# Snapshot du cycle courant
curl -s https://api.coffrify.com/v1/billing/snapshot \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# Recommandation de plan (30j)
curl -s https://api.coffrify.com/v1/billing/recommendation \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# Recommandation diagnostics sur 60 jours
curl -s "https://api.coffrify.com/v1/diagnostics/plan-recommendation?range_days=60" \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"

Réponse : snapshot de facturation

Le snapshot expose l'usage réel du cycle en cours, l'overage projeté et le bilan du mois précédent. C'est la vue à privilégier pour un tableau de bord de facturation.

{
  "object": "billing_snapshot",
  "current_period": {
    "period": "2026-06",
    "plan": "pro",
    "storage_quota_gb": 50,
    "bandwidth_quota_gb": 100,
    "storage_used_gb": 38.4721,
    "bandwidth_used_gb": 12.8843,
    "storage_overage_gb": 0,
    "bandwidth_overage_gb": 0,
    "projected_overage": {
      "storage_eur": 0,
      "bandwidth_eur": 0,
      "total_eur": 0
    },
    "overage_rates": {
      "storage_eur_per_gb": 0.05,
      "bandwidth_eur_per_gb": 0.02
    }
  },
  "previous_period": {
    "period": "2026-05",
    "plan": "pro",
    "storage_used_gb": 41.22,
    "bandwidth_used_gb": 108.74,
    "storage_overage_gb": 0,
    "bandwidth_overage_gb": 8.74,
    "storage_amount_eur": 0,
    "bandwidth_amount_eur": 0.17,
    "total_billed_eur": 0.17,
    "reported_to_stripe": true,
    "reported_at": "2026-06-01T02:14:07.000Z"
  },
  "downgrade_impact": null
}

Réponse : recommandation de plan

La recommandation analyse 30 jours d'usage et renvoie le plan optimal, la direction (upgrade, downgrade ou stay) et le delta de coût mensuel estimé.

{
  "workspace_id": "ws_01HZ8KPQMRN2XYTV4GBD7SWFE",
  "current_plan": "pro",
  "usage_30d": {
    "storage_gb": 38.47,
    "bandwidth_gb": 12.88,
    "active_transfers": 14
  },
  "recommended_plan": "pro",
  "direction": "stay",
  "savings_or_cost_delta_eur_per_month": 0,
  "annual_savings_pct_vs_monthly": 17,
  "rationale": "Your pro plan is well-sized for your usage. No change needed.",
  "next_tool": null,
  "plan_caps": [
    { "plan": "free",  "storage_gb": 5,   "bandwidth_gb": 10,  "monthly_cents": 0,    "annual_cents": 0 },
    { "plan": "pro",   "storage_gb": 50,  "bandwidth_gb": 100, "monthly_cents": 4999, "annual_cents": 49900 },
    { "plan": "ultra", "storage_gb": 500, "bandwidth_gb": 1000,"monthly_cents": 7999, "annual_cents": 79900 }
  ]
}

Cas : rétrogradation en cours de mois

Lorsqu'un workspace rétrograde de plan en cours de cycle (ex. Ultra vers Pro), le champ downgrade_impact du snapshot n'est pas null et expose le nouveau quota ainsi que l'overage qui résulterait si le mois se terminait avec ce nouveau quota. Utilisez ce signal pour alerter proactivement vos utilisateurs avant la clôture du cycle.

{
  "downgrade_impact": {
    "plan_changed_at": "2026-06-04T09:23:11.000Z",
    "new_quota_storage_gb": 50,
    "new_quota_bandwidth_gb": 100,
    "storage_overage_gb_with_new_quota": 12.47,
    "bandwidth_overage_gb_with_new_quota": 0
  }
}

Erreurs

Les erreurs portent surtout sur le scope billing:read (réservé aux plans Pro et Ultra) ou une fenêtre de jours hors bornes. Le tableau ci-dessous indique la résolution.

Voir aussi

• Créer un lien de checkout
• Consulter l'usage et les quotas
• Référence : Billing Snapshot
• Référence : Billing Recommendation
• Référence : Diagnostics Plan Recommendation
• Gestion des clés API et scopes