Saltearse al contenido

API de Facturación

Tres endpoints permiten a los agentes e integraciones trabajar con el estado de facturación que gestiona su dashboard.

Todos los endpoints requieren una API key Bearer (consulte Autenticación).

GET /me/billing/state

Devuelve una instantánea de la suscripción de su tenant.

Ventana de terminal
curl https://api.saiku.bi/me/billing/state \
-H "Authorization: Bearer $SAIKU_API_KEY"

Respuesta:

{
"tenantId": "81e301f2-…",
"tier": "team",
"stripeCustomerId": "cus_…",
"subscriptionStatus": "active",
"currentPeriodEnd": "2026-06-23T00:00:00Z",
"trialEndsAt": null,
"billedFeaturesActive": true
}

Campos:

  • tier — starter, team, business o enterprise.
  • subscriptionStatus — el estado literal de Stripe. Los valores que verá en la práctica son trialing, active, past_due, unpaid, canceled o vacío (gratis / pre-facturación).
  • currentPeriodEnd — cuándo termina su período de facturación actual. La renovación ocurre en este momento si está activo.
  • trialEndsAt — solo establecido mientras subscriptionStatus = trialing.
  • billedFeaturesActive — true mientras tiene acceso a las funcionalidades facturadas. Falso en caso contrario. Use esto para controlar el acceso en su propia UI.

Dos formas, no una

Un tenant que nunca ha iniciado una suscripción no tiene registro de facturación detrás, y la respuesta es más corta — solo lleva:

{
"tenantId": "81e301f2-…",
"tier": "starter",
"subscriptionStatus": "",
"billedFeaturesActive": false
}

stripeCustomerId, currentPeriodEnd y trialEndsAt están ausentes, no en null. Si su cliente lee state.currentPeriodEnd esperando un null, recibe undefined — así que ramifique por billedFeaturesActive (o por la presencia de la clave) en vez de suponer que todos los campos están siempre.

Cuando la facturación no está configurada

Si la gateway no tiene clave de Stripe cableada, todos los endpoints de esta página devuelven 503:

{
"error": "billing_disabled",
"message": "Stripe billing is not configured on this gateway."
}

Verá esto en builds autoalojados y stacks locales, donde es lo esperado. En api.saiku.bi no lo es — si se lo encuentra ahí, dígannoslo.

POST /me/billing/checkout-session

Genera una URL de un solo uso al Checkout alojado de Stripe para iniciar una prueba o suscribirse a un plan.

Ventana 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"
}'

Respuesta:

{
"url": "https://checkout.stripe.com/c/pay/cs_test_a1…",
"sessionId": "cs_test_a1…"
}

Envíe el navegador del usuario a url mediante una redirección 303. La URL es de un solo uso y expira en pocos minutos — no la guarde en caché.

successUrl y cancelUrl son URLs absolutas a las que Stripe envía al usuario después de completar o abandonar el Checkout. Ambas deben ser HTTPS.

POST /me/billing/portal-session

Genera una URL de un solo uso al Customer Portal de Stripe. El Portal es la página alojada de Stripe para gestionar la suscripción: actualizar tarjeta, cambiar de plan, descargar facturas, cancelar.

Ventana 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" }'

Respuesta:

{ "url": "https://billing.stripe.com/p/session/test_…" }

Devuelve 409 no_customer si el tenant nunca ha completado el Checkout — no hay cliente de Stripe que gestionar. Ejecute POST /me/billing/checkout-session primero.

Un ejemplo trabajado — estado de suscripción incrustado

Si está construyendo una interfaz de administración que envuelve a Saiku Cloud y quiere mostrar a sus usuarios su plan actual en línea:

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