Aller au contenu

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.

Fenêtre de terminal
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, business ou enterprise.
  • subscriptionStatus — statut Stripe tel quel. Les valeurs que vous verrez en pratique sont trialing, 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 que subscriptionStatus = trialing.
  • billedFeaturesActive — true tant 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.

Fenêtre de terminal
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.

Fenêtre de terminal
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 :

// pseudocode
const 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);
}