API de Billing
Três endpoints permitem que agentes e integrações trabalhem com o estado de billing que seu dashboard gerencia.
Todos os endpoints exigem uma API key Bearer (veja Autenticação).
GET /me/billing/state
Retorna um snapshot da assinatura do seu tenant.
curl https://api.saiku.bi/me/billing/state \ -H "Authorization: Bearer $SAIKU_API_KEY"Resposta:
{ "tenantId": "81e301f2-…", "tier": "team", "stripeCustomerId": "cus_…", "subscriptionStatus": "active", "currentPeriodEnd": "2026-06-23T00:00:00Z", "trialEndsAt": null, "billedFeaturesActive": true}Campos:
tier—starter,team,businessouenterprise.subscriptionStatus— status do Stripe literalmente. Os valores que você verá na prática sãotrialing,active,past_due,unpaid,canceledou vazio (free / pré-billing).currentPeriodEnd— quando o seu período atual de billing termina. A renovação acontece nesse ponto se estiver ativa.trialEndsAt— definido apenas enquantosubscriptionStatus = trialing.billedFeaturesActive—trueenquanto você tem acesso aos recursos pagos. Falso caso contrário. Use isso para controlar sua própria UI.
Dois formatos, não um
Um tenant que nunca começou uma assinatura não tem registro de billing por trás, e a resposta é mais curta — ela carrega só:
{ "tenantId": "81e301f2-…", "tier": "starter", "subscriptionStatus": "", "billedFeaturesActive": false}stripeCustomerId, currentPeriodEnd e trialEndsAt estão
ausentes, não nulos. Se o seu cliente lê state.currentPeriodEnd
esperando um null, ele recebe undefined — então ramifique por
billedFeaturesActive (ou pela presença da chave) em vez de assumir que
todo campo está sempre lá.
Quando o billing não está configurado
Se a gateway não tem chave do Stripe ligada, todo endpoint desta página
devolve 503:
{ "error": "billing_disabled", "message": "Stripe billing is not configured on this gateway."}Você vai ver isso em builds self-hosted e stacks locais, onde é
esperado. Em api.saiku.bi não é — se topar com isso lá, nos avise.
POST /me/billing/checkout-session
Gera uma URL única para o Checkout hospedado do Stripe para iniciar um teste ou assinar um plano.
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" }'Resposta:
{ "url": "https://checkout.stripe.com/c/pay/cs_test_a1…", "sessionId": "cs_test_a1…"}Direcione o navegador do usuário para url via um redirect 303. A URL é
de uso único e expira após alguns minutos — não a cacheie.
successUrl e cancelUrl são URLs absolutas para onde o Stripe envia o usuário
de volta após completar ou abandonar o Checkout. Ambas devem ser
HTTPS.
POST /me/billing/portal-session
Gera uma URL única para o Customer Portal do Stripe. O Portal é a página hospedada pelo Stripe para gerenciar a assinatura: atualizar cartão, mudar plano, baixar faturas, cancelar.
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" }'Resposta:
{ "url": "https://billing.stripe.com/p/session/test_…" }Retorna 409 no_customer se o tenant nunca tiver concluído o
Checkout — não há nenhum customer do Stripe para gerenciar. Execute
POST /me/billing/checkout-session primeiro.
Um exemplo prático — estado da assinatura embutido
Se você está construindo uma UI de admin que envolve o Saiku Cloud e quer mostrar aos seus usuários o plano atual inline:
// 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);}