# EPICA: EPIC-MGN-017 - Integracion Stripe

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-017 |
| **Nombre** | Integracion Stripe para Suscripciones |
| **Modulo** | billing |
| **Fase** | Fase 4 - SaaS Platform |
| **Prioridad** | P0 |
| **Estado** | Backlog |
| **Story Points** | 34 |
| **Sprint(s)** | Sprint 22-24 |

---

## Descripcion

Integracion completa con Stripe para gestion de suscripciones por usuario, cobros recurrentes, prorratas automaticas, y webhooks para sincronizacion de estado.

---

## Objetivo de Negocio

- Automatizar cobros recurrentes por suscripcion
- Soportar modelo per-seat con prorratas
- Facilitar cambios de plan (upgrade/downgrade)
- Mantener sincronizacion bidireccional con Stripe

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN017-001 | Como tenant owner, quiero vincular mi cuenta con Stripe | P0 | 3 | Backlog |
| US-MGN017-002 | Como tenant owner, quiero agregar tarjeta de credito | P0 | 5 | Backlog |
| US-MGN017-003 | Como sistema, quiero crear suscripcion en Stripe al activar tenant | P0 | 5 | Backlog |
| US-MGN017-004 | Como sistema, quiero actualizar cantidad de usuarios en Stripe | P0 | 5 | Backlog |
| US-MGN017-005 | Como sistema, quiero procesar webhooks de Stripe | P0 | 8 | Backlog |
| US-MGN017-006 | Como sistema, quiero manejar pagos fallidos | P0 | 5 | Backlog |
| US-MGN017-007 | Como tenant owner, quiero ver portal de facturacion Stripe | P1 | 3 | Backlog |

**Total Story Points:** 34 SP

---

## Criterios de Aceptacion

**Funcionales:**
- [ ] Crear Customer en Stripe al registrar tenant
- [ ] Agregar/actualizar metodos de pago via Stripe Elements
- [ ] Crear Subscription con quantity = usuarios
- [ ] Actualizar quantity automaticamente al agregar/remover usuarios
- [ ] Procesar webhooks: invoice.paid, payment_failed, subscription.updated, etc.
- [ ] Cancelar suscripcion al final del periodo
- [ ] Redirigir a Stripe Customer Portal

**No Funcionales:**
- [ ] Webhook retry logic
- [ ] Idempotencia en procesamiento de webhooks
- [ ] Logs de todas las transacciones

---

## Webhooks a Implementar

| Evento | Accion |
|--------|--------|
| customer.subscription.created | Registrar suscripcion |
| customer.subscription.updated | Actualizar estado/cantidad |
| customer.subscription.deleted | Marcar suscripcion cancelada |
| invoice.created | Registrar factura draft |
| invoice.finalized | Actualizar factura a open |
| invoice.paid | Marcar factura pagada, activar tenant |
| invoice.payment_failed | Alertar, iniciar dunning |
| payment_intent.succeeded | Registrar pago |
| payment_intent.payment_failed | Registrar intento fallido |

---

## Dependencias

**Depende de:**
- EPIC-MGN-016 Billing (Ready)
- EPIC-MGN-004 Tenants (Ready)

**Bloquea:**
- EPIC-MGN-018 WhatsApp (feature flag por plan)
- EPIC-MGN-019 AI Agents (feature flag por plan)

---

## Desglose Tecnico

**Database:**
- [ ] Tabla: stripe_customers
- [ ] Tabla: stripe_webhook_events

**Backend:**
- [ ] Service: StripeService
- [ ] Controller: StripeWebhookController
- [ ] Job: SyncStripeDataJob

**Integraciones:**
- [ ] Stripe SDK (Node.js)
- [ ] Stripe Elements (Frontend)
- [ ] Stripe Customer Portal

---

**Creado por:** Requirements-Analyst
**Fecha:** 2025-12-05