Billing API

Objetivo

Operar el ciclo completo de facturación recurrente: iniciar checkout, confirmar estado post-pago y habilitar autoservicio con trazabilidad por organización.

Endpoints y contrato operativo

Flujo recomendado

1. 11) Crear checkout

   Genera sesión con plan, ciclo y contexto de organización. Guarda checkoutSessionId.

2. 22) Redirigir usuario

   Envía al usuario a redirectUrl y evita submits concurrentes en frontend.

3. 33) Confirmar estado

   Tras el retorno del checkout, llama subscription/confirm. Si tienes el session_id de la success URL, envíalo como sessionId.

4. 44) Exponer portal

   Genera sesiones de portal solo cuando ya existe un cliente/suscripción Stripe gestionable.

Ejemplo de creación de checkout

curl -X POST "https://test.beacon.pt/api/billing/subscription/checkout?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plus",
    "billingCycle": "monthly"
  }'

{
  "ok": true,
  "checkoutSessionId": "cs_123",
  "redirectUrl": "https://checkout.stripe.com/c/pay/cs_123",
  "plan": "PLUS",
  "billingCycle": "monthly",
  "context": {
    "mode": "test",
    "organizationSlug": "acme"
  }
}

Confirmación y consistencia

• El checkout no expone un Idempotency-Key público; la clave Stripe se genera en servidor.
• Si ya existe un checkout pendiente para el mismo plan y ciclo, la API puede reutilizarlo y devolver pending: true.
• Si existe un checkout pendiente para otro plan o la organización ya tiene una suscripción activa, la API responde con 409.
• No asumas éxito solo por el redirect; confirma el estado final por subscription/confirm y eventos Stripe.

Ejemplo de confirmación

curl -X POST "https://test.beacon.pt/api/billing/subscription/confirm?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"cs_test_a1b2c3"}'

{
  "ok": true,
  "subscription": {
    "plan": "PLUS",
    "status": "ACTIVE"
  },
  "context": {
    "mode": "test",
    "organizationSlug": "acme"
  }
}

Errores frecuentes

Checklist de go-live

• Flujo completo validado en mode=test sin estados pendientes.
• Alertas activas para fallos de confirmación y picos de retries.
• Portal limitado por perfil con trazabilidad de acceso.