Stripe Billing

O modulo de Stripe Billing implementa um sistema completo de assinaturas SaaS com 3 planos pre-configurados, Stripe Checkout, Customer Portal e processamento de webhooks.

Plano	Features
Free	1 projeto, analytics basico, suporte comunidade, 1 GB storage
Pro	Projetos ilimitados, analytics avancado, suporte prioritario, 50 GB, dominio custom, 5 membros
Enterprise	Tudo ilimitado, account manager dedicado, SSO/SAML, SLA, audit logs

Os planos sao definidos em apps/api/src/billing/plans.config.ts:

export const plans: Plan[] = [
  {
    id: 'free',
    name: 'Free',
    priceId: process.env.STRIPE_PRICE_FREE || 'price_free_placeholder',
    mode: 'subscription',
    interval: 'month',
    features: ['Up to 1 project', 'Basic analytics', ...],
  },
  {
    id: 'pro',
    name: 'Pro',
    priceId: process.env.STRIPE_PRICE_PRO || 'price_pro_placeholder',
    // ...
  },
  // ...
];

Metodo	Rota	Descricao
GET	/api/billing/plans	Lista planos disponiveis
POST	/api/billing/create-checkout-session	Cria sessao de checkout Stripe
POST	/api/billing/create-portal-session	Cria sessao do Customer Portal
GET	/api/billing/subscription-status	Status da assinatura do usuario
POST	/api/billing/webhook	Webhook do Stripe (raw body)

Para iniciar uma assinatura, crie uma Checkout Session:

// Frontend
const response = await fetch('/api/billing/create-checkout-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customerId: 'cus_xxx',        // ID do Stripe Customer
    priceId: 'price_xxx',         // ID do Price no Stripe
    successUrl: 'http://localhost:3000/billing/success',
    cancelUrl: 'http://localhost:3000/billing/cancel',
  }),
});

const { url } = await response.json();
window.location.href = url;       // Redireciona para o Stripe Checkout

O endpoint de webhook processa os seguintes eventos do Stripe:

• customer.subscription.created — Nova assinatura criada
• customer.subscription.updated — Assinatura alterada (upgrade/downgrade)
• customer.subscription.deleted — Assinatura cancelada
• invoice.payment_succeeded — Pagamento realizado com sucesso
• invoice.payment_failed — Pagamento falhou

Importante: O endpoint de webhook precisa receber o raw body (Buffer) para verificacao da assinatura Stripe. O PlazerCLI ja configura isso automaticamente para cada backend.

Para testar webhooks localmente, use o Stripe CLI:

stripe listen --forward-to localhost:3001/api/billing/webhook

# Obtenha em https://dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY=sk_test_...

# Obtenha do Stripe CLI ou dashboard de webhooks
STRIPE_WEBHOOK_SECRET=whsec_...

# IDs dos precos criados no Stripe Dashboard
STRIPE_PRICE_FREE=price_...
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_ENTERPRISE=price_...

O Stripe Customer Portal permite que o usuario gerencie sua assinatura diretamente (upgrade, downgrade, cancelar, atualizar cartao):

// Frontend
const response = await fetch('/api/billing/create-portal-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customerId: 'cus_xxx',
    returnUrl: 'http://localhost:3000/settings/billing',
  }),
});

const { url } = await response.json();
window.location.href = url; // Redireciona para o Stripe Portal

Configure o portal no Stripe Dashboard > Settings > Billing > Customer Portal.