Diseña e implementa la infraestructura técnica de facturación recurrente: integración con Stripe, gestión de planes, ciclos de vida del pago y manejo de fallos.
Cuándo usarlo: Arquitectura técnica de un sistema de facturación recurrente robusto
Herramienta recomendada: Claude
Actúa como un ingeniero de software senior especializado en arquitectura de sistemas de facturación recurrente para productos SaaS y plataformas de suscripción. Necesito diseñar o mejorar la arquitectura técnica de facturación recurrente de nuestro producto. Quiero construir un sistema robusto, escalable y que maneje correctamente todos los estados del ciclo de vida de una suscripción. Nuestro stack tecnológico es: [lenguaje, framework backend, base de datos, si usamos Stripe/Paddle/Chargebee/otro] La complejidad de nuestros planes es: [número de planes, si hay trials, freemium, add-ons, por uso, por asientos] Los problemas actuales son: [pagos fallidos sin recuperar, webhooks inconsistentes, modelos de datos confusos, dificultad para añadir nuevos planes] Necesito que me expliques: **1. Modelado de datos para suscripciones** Explícame cómo modelar correctamente las entidades principales de un sistema de suscripción en la base de datos: Customer, Subscription, SubscriptionItem, Plan, Price, Invoice, PaymentMethod, CreditNote. Detalla las relaciones entre ellas, qué campos son críticos en cada entidad, cómo manejar los estados de suscripción (trialing, active, past_due, canceled, unpaid) y por qué es un error depender completamente del modelo de datos del proveedor de pagos en lugar de mantener tu propio modelo sincronizado. **2. Integración con Stripe: webhooks y sincronización de estado** Explícame la arquitectura correcta para integrar Stripe en un sistema de suscripción: cómo configurar y procesar los webhooks de Stripe de forma idempotente, qué eventos son críticos y cuáles se pueden ignorar (customer.subscription.updated, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted), cómo manejar la entrega at-least-once de los webhooks, cómo sincronizar el estado de Stripe con tu base de datos local de forma resiliente usando una cola de mensajes. **3. Manejo de fallos de pago y recuperación de ingresos** Detalla la lógica de recuperación de pagos fallidos: smart retries automáticos de Stripe (Dunning), notificaciones proactivas al cliente antes y después del fallo (email de actualización de tarjeta), flujo de actualización de método de pago, cuándo pasar una suscripción a estado past_due vs. unpaid vs. canceled, cómo implementar un grace period configurable. Explícame cómo impacta cada decisión en el revenue recovery rate. **4. Facturación por uso (usage-based billing)** Explícame cómo implementar facturación por uso sobre Stripe: los modelos de precios por uso (per-unit, tiered, volume), cómo reportar el uso mediante la API de usage records, cómo manejar la concurrencia cuando múltiples procesos reportan uso simultáneamente, cómo construir un medidor de uso interno que sea la fuente de verdad antes de enviar los datos a Stripe, y cómo mostrar al usuario su consumo en tiempo real dentro del producto. **5. Multi-tenancy, upgrades y downgrades** Explícame cómo manejar técnicamente los cambios de plan (upgrades y downgrades) de forma correcta: proration en Stripe (immediate vs. next billing cycle), cómo reflejar el cambio inmediatamente en los permisos del usuario sin esperar al siguiente ciclo de facturación, cómo gestionar add-ons y SubscriptionItems adicionales, cómo manejar suscripciones con múltiples asientos y el billing por seat con usuarios añadidos o eliminados durante el ciclo. **6. Testing y monitorización de la infraestructura de billing** Dime cómo testear correctamente un sistema de suscripción: uso del entorno de test de Stripe, cómo simular eventos de webhook en tests de integración, qué scenarios críticos siempre deben tener cobertura (primer cargo, fallo de pago, recuperación, cancelación, reactivación). Explícame también qué alertas y métricas de monitorización debo configurar: tasa de fallos de webhook, latencia en el procesamiento de eventos, tasa de pagos fallidos, MRR calculado internamente vs. Stripe dashboard. Incluye código de ejemplo donde sea relevante y señala los cinco antipatrones más comunes en implementaciones de billing recurrente que causan pérdida de ingresos o deuda técnica severa.