Pular para o conteúdo
Saiku Cloud

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.

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