Pular para o conteúdo

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.

Terminal window
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, business ou enterprise.
  • subscriptionStatus — status do Stripe literalmente. Os valores que você verá na prática são trialing, active, past_due, unpaid, canceled ou 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 enquanto subscriptionStatus = trialing.
  • billedFeaturesActive — true enquanto 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.

Terminal window
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.

Terminal window
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:

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