Abonnement et facturation

Consultez le plan, le statut et la période de l'abonnement de votre espace via l'API REST v1, avec le scope billing:read.

L'API de facturation vous donne une vue en lecture sur l'abonnement de votre espace de travail : le plan en cours, l'état du compte client de paiement et, le cas échéant, l'historique d'un abonnement hérité. Tout passe par un seul appel principal, GET /v1/billing/subscription, protégé par le scope billing:read. Cette page explique comment lire ces informations, ce que contient la réponse, où récupérer l'adresse de facturation, et quels évènements webhook vous préviennent quand l'abonnement change.

Authentification et scope

Toutes les requêtes ciblent la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>. La lecture de l'abonnement exige le scope billing:read sur la clé. Une clé qui ne porte pas ce scope reçoit une réponse 403 avec le code scope_missing ; vérifiez les scopes attribués à votre clé avant d'appeler.

Consulter l'abonnement

GET/v1/billing/subscriptionRenvoie le plan en cours de l'espace, l'état du compte de paiement et l'abonnement hérité éventuel. Scope requis : billing:read.

L'appel ne prend aucun paramètre : il renvoie toujours l'abonnement de l'espace de travail rattaché à la clé. Voici comment l'invoquer avec le SDK JavaScript/TypeScript ou directement en REST.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const subscription = await coffrify.billing.getSubscription();
 
console.log(subscription.workspace.plan);
console.log(subscription.stripe.has_active_subscription);

Structure de la réponse

La réponse se compose de trois blocs : workspace pour le plan en cours, stripe pour l'état du compte de paiement, et legacy_user_subscription pour un éventuel abonnement individuel antérieur (sinon null).

{
  "workspace": {
    "id": "d6f7a1c2-3b4e-4a5f-9c0d-1e2f3a4b5c6d",
    "name": "Cabinet Durand",
    "slug": "cabinet-durand",
    "plan": "pro"
  },
  "stripe": {
    "customer_id": "cus_xxxxxxxxxxxx",
    "subscription_id": "sub_xxxxxxxxxxxx",
    "has_active_subscription": true
  },
  "legacy_user_subscription": null
}

Champ	Type	Description
workspace.id	string	Identifiant de l'espace de travail.
workspace.name	string \| null	Nom affiché de l'espace.
workspace.slug	string \| null	Identifiant lisible de l'espace.
workspace.plan	string	Plan en cours, par exemple `free`, `pro` ou `ultra`.
stripe.customer_id	string \| null	Référence du compte de paiement, `null` tant qu'aucun n'existe.
stripe.subscription_id	string \| null	Référence de l'abonnement payant, `null` sur un plan gratuit.
stripe.has_active_subscription	boolean	`true` si un abonnement payant est actif.
legacy_user_subscription	object \| null	Abonnement individuel hérité (statut, dates) ou `null`.

Où trouver l'adresse de facturation

L'adresse de facturation n'est pas incluse dans la réponse de l'abonnement : elle se lit séparément avec GET /v1/billing/address (toujours scope billing:read). Cet appel renvoie un objet address contenant les informations fiscales et postales de l'espace, ou null si rien n'a encore été renseigné.

GET/v1/billing/addressRenvoie l'adresse de facturation de l'espace (raison sociale, numéro de TVA, pays, etc.) ou null. Scope requis : billing:read.

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

Réagir aux changements (webhooks)

Plutôt que d'interroger l'abonnement en boucle, abonnez-vous aux évènements webhook qui signalent un changement. Vous synchronisez ainsi votre propre système au moment exact où l'état évolue côté Coffrify.

Évènement	Déclenchement
workspace.plan_changed	Le plan de l'espace a changé (passage à un palier supérieur ou inférieur).
billing.trial_started	Une période d'essai vient de démarrer.
billing.trial_ending	La période d'essai approche de son terme.
billing.subscription_cancelled	L'abonnement a été résilié.

À la réception d'un de ces évènements, rappelez GET /v1/billing/subscription pour récupérer l'état complet et à jour, puis mettez votre cache à jour. Pensez à traiter chaque livraison de façon idempotente côté récepteur, car un même évènement peut être livré plus d'une fois.