template-saas/docs/01-modulos/SAAS-004-billing.md

SAAS-004: Billing y Suscripciones

Metadata

• Codigo: SAAS-004
• Modulo: Billing
• Prioridad: P0
• Estado: Completado
• Fase: 2 - Billing

Descripcion

Sistema de facturacion completo con Stripe: suscripciones recurrentes, trials, upgrades/downgrades, facturas, y webhooks para sincronizacion.

Objetivos

1. Integracion completa con Stripe
2. Suscripciones mensuales/anuales
3. Trial period (14 dias)
4. Upgrade/downgrade de plan
5. Facturas y recibos

Alcance

Incluido

• Stripe Checkout
• Suscripciones recurrentes
• Trial gratuito
• Cambio de plan (prorateo)
• Portal de cliente Stripe
• Webhooks de Stripe
• Historial de facturas

Excluido

• Metered billing - fase posterior
• Multiples metodos de pago guardados
• Facturacion fiscal mexicana

Modelo de Datos

Tablas (schema: billing)

subscriptions

• id, tenant_id, plan_id
• stripe_subscription_id, stripe_customer_id
• status, current_period_start, current_period_end
• trial_ends_at, cancelled_at

invoices

• id, tenant_id, subscription_id
• stripe_invoice_id, number
• amount, currency, status
• paid_at, pdf_url

Integracion Stripe

Productos y Precios

// Configurados en Stripe Dashboard
const STRIPE_PRODUCTS = {
  starter: {
    monthly: 'price_xxx_monthly',
    yearly: 'price_xxx_yearly'
  },
  pro: {
    monthly: 'price_yyy_monthly',
    yearly: 'price_yyy_yearly'
  }
};

Webhooks Manejados

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• customer.updated

Endpoints API

Metodo	Endpoint	Descripcion
GET	/billing/plans	Planes disponibles
GET	/billing/subscription	Suscripcion actual
POST	/billing/checkout	Crear sesion checkout
POST	/billing/portal	URL portal de cliente
PUT	/billing/change-plan	Cambiar plan
POST	/billing/cancel	Cancelar suscripcion
POST	/billing/resume	Reanudar suscripcion
GET	/billing/invoices	Historial facturas
GET	/billing/invoices/:id/pdf	Descargar factura
POST	/billing/webhook	Webhook Stripe

Flujos

Nueva Suscripcion

1. Usuario selecciona plan
2. Click "Suscribirse"
3. Backend crea Checkout Session
4. Usuario redirigido a Stripe Checkout
5. Usuario completa pago
6. Stripe envia webhook
7. Backend actualiza suscripcion
8. Usuario redirigido a app

Upgrade de Plan

1. Usuario en plan Starter
2. Click "Upgrade a Pro"
3. Backend llama Stripe API
4. Stripe calcula prorateo
5. Se cobra diferencia
6. Plan actualizado inmediatamente
7. Features Pro desbloqueadas

Trial Expirando

Dia -3: Email "Tu trial termina en 3 dias"
Dia -1: Email "Tu trial termina manana"
Dia 0: Email "Tu trial ha terminado"
        Si no hay pago: downgrade a Free

Estados de Suscripcion

trialing ──► active ──► past_due ──► cancelled
                │
                └──► paused

Estado	Acceso	Descripcion
trialing	Completo	En periodo de prueba
active	Completo	Pagando
past_due	Limitado	Pago fallido (grace)
cancelled	Sin acceso	Cancelada
paused	Sin acceso	Pausada

Entregables

Entregable	Estado	Archivo
billing.module.ts	Completado	modules/billing/
stripe.service.ts	Completado	services/
billing.controller.ts	Completado	controllers/
DDL billing schema	Completado	ddl/schemas/billing/

Dependencias

Depende de

• SAAS-001 (Auth)
• SAAS-002 (Tenants)
• SAAS-005 (Plans)

Bloquea a

• Ninguno (pero habilita features por plan)

Criterios de Aceptacion

• Checkout funciona
• Webhooks se procesan
• Upgrade/downgrade funciona
• Facturas se generan
• Trial funciona
• Cancelacion funciona

Configuracion

{
  stripe: {
    secretKey: process.env.STRIPE_SECRET_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
    portalReturnUrl: 'https://app.example.com/settings/billing'
  },
  trial: {
    days: 14,
    requiresCard: false
  }
}

---

Ultima actualizacion: 2026-01-07