Billing API

Objetivo

Operar o ciclo completo de faturação recorrente: iniciar checkout, confirmar estado pós-pagamento e abrir portal self-service sem perder rastreabilidade por organização.

Endpoints e contrato operativo

Fluxo recomendado

1. 11) Criar checkout

   Gera sessão com plano, ciclo e contexto de organização. Guarda o checkoutSessionId para rastreio.

2. 22) Redirecionar utilizador

   Envia o utilizador para redirectUrl e evita submits concorrentes no frontend.

3. 33) Confirmar resultado

   Após o retorno do checkout, chama subscription/confirm. Se tiveres o session_id do success URL, envia-o como sessionId.

4. 44) Expor portal

   Disponibiliza subscription/portal apenas quando já existe cliente/subscrição Stripe gerível.

Exemplo de criação 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"
  }
}

Confirmação e consistência

• O checkout não expõe Idempotency-Key pública; a chave usada na Stripe é gerada no servidor.
• Se já existir checkout pendente para o mesmo plano e ciclo, a API pode reutilizar a sessão pendente e devolver pending: true.
• Se existir checkout pendente para outro plano ou se a organização já tiver subscrição activa, a API responde com 409.
• Não assumes sucesso apenas com o redirect concluído; o estado final deve ser confirmado por subscription/confirm e por eventos Stripe.

Exemplo de confirmação

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

Erros frequentes

Checklist de go-live

• Fluxo testado em mode=test com sucesso e sem estados pendentes.
• Alertas ativos para falhas de confirmação e aumento de retries.
• Portal restrito por perfil e com auditoria de acesso.