API de facturation
Trois endpoints permettent aux agents et intégrations de travailler avec l’état de facturation géré par votre dashboard.
Tous les endpoints nécessitent une clé API Bearer (voir Authentification).
GET /me/billing/state
Renvoie un instantané de l’abonnement de votre tenant.
curl https://api.saiku.bi/me/billing/state \ -H "Authorization: Bearer $SAIKU_API_KEY"Réponse :
{ "tenantId": "81e301f2-…", "tier": "team", "stripeCustomerId": "cus_…", "subscriptionStatus": "active", "currentPeriodEnd": "2026-06-23T00:00:00Z", "trialEndsAt": null, "billedFeaturesActive": true}Champs :
tier—starter,team,businessouenterprise.subscriptionStatus— statut Stripe tel quel. Les valeurs que vous verrez en pratique sonttrialing,active,past_due,unpaid,canceled, ou vide (gratuit / pré-facturation).currentPeriodEnd— date de fin de votre période de facturation actuelle. Le renouvellement intervient à cette date si l’abonnement est actif.trialEndsAt— défini uniquement tant quesubscriptionStatus = trialing.billedFeaturesActive—truetant que vous avez accès aux fonctionnalités facturées. False sinon. Utilisez ce champ pour contrôler votre propre interface.
Deux formes, pas une
Un tenant qui n’a jamais démarré d’abonnement n’a aucun enregistrement de facturation derrière lui, et la réponse est plus courte — elle ne porte que :
{ "tenantId": "81e301f2-…", "tier": "starter", "subscriptionStatus": "", "billedFeaturesActive": false}stripeCustomerId, currentPeriodEnd et trialEndsAt sont
absents, pas null. Si votre client lit state.currentPeriodEnd en
attendant un null, il obtient undefined — testez donc
billedFeaturesActive (ou la présence de la clé) plutôt que de supposer
que chaque champ est toujours là.
Quand la facturation n’est pas configurée
Si la gateway n’a pas de clé Stripe câblée, chaque point d’entrée de
cette page renvoie 503 :
{ "error": "billing_disabled", "message": "Stripe billing is not configured on this gateway."}Vous verrez cela sur les builds auto-hébergés et les stacks locaux, où
c’est attendu. Sur api.saiku.bi, non — si vous tombez dessus là-bas,
dites-le-nous.
POST /me/billing/checkout-session
Crée une URL à usage unique vers Stripe Checkout (hébergé) pour démarrer un essai ou souscrire à un plan.
curl -X POST https://api.saiku.bi/me/billing/checkout-session \ -H "Authorization: Bearer $SAIKU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tier": "team", "email": "alice@acme.com", "name": "Acme Corp", "successUrl": "https://app.acme.com/billing/success", "cancelUrl": "https://app.acme.com/billing/cancel" }'Réponse :
{ "url": "https://checkout.stripe.com/c/pay/cs_test_a1…", "sessionId": "cs_test_a1…"}Envoyez le navigateur de l’utilisateur vers url via une
redirection 303. L’URL est à usage unique et expire au bout de
quelques minutes — ne la mettez pas en cache.
successUrl et cancelUrl sont des URL absolues vers
lesquelles Stripe renvoie l’utilisateur après la finalisation ou
l’abandon du Checkout. Les deux doivent être en HTTPS.
POST /me/billing/portal-session
Crée une URL à usage unique vers le portail client Stripe. Le portail est la page hébergée par Stripe pour gérer l’abonnement : mettre à jour la carte, changer de plan, télécharger les factures, annuler.
curl -X POST https://api.saiku.bi/me/billing/portal-session \ -H "Authorization: Bearer $SAIKU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "returnUrl": "https://app.acme.com/billing" }'Réponse :
{ "url": "https://billing.stripe.com/p/session/test_…" }Renvoie 409 no_customer si le tenant n’a jamais finalisé de
Checkout — il n’y a pas de client Stripe à gérer. Exécutez
d’abord POST /me/billing/checkout-session.
Un exemple concret — état d’abonnement embarqué
Si vous construisez une interface d’administration qui enveloppe Saiku Cloud et souhaitez afficher à vos utilisateurs leur plan actuel directement :
// pseudocodeconst state = await fetch('https://api.saiku.bi/me/billing/state', { headers: { Authorization: `Bearer ${saikuApiKey}` }}).then(r => r.json());
if (!state.billedFeaturesActive) { // user has no active subscription or trial — show "upgrade" CTA const session = await fetch( 'https://api.saiku.bi/me/billing/checkout-session', { method: 'POST', headers: { Authorization: `Bearer ${saikuApiKey}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ tier: 'team', email: user.email, name: org.name, successUrl: `${window.location.origin}/billing/success`, cancelUrl: `${window.location.origin}/billing/cancel` }) } ).then(r => r.json()); window.location.href = session.url;} else { // user has access — show current plan + manage button renderPlan(state.tier, state.currentPeriodEnd); const portal = await fetch( 'https://api.saiku.bi/me/billing/portal-session', { method: 'POST', headers: { Authorization: `Bearer ${saikuApiKey}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ returnUrl: `${window.location.origin}/billing` }) } ).then(r => r.json()); renderManageButton(portal.url);}