Diseña e implementa la arquitectura técnica de un sistema de suscripciones recurrentes, integrando pasarelas de pago, gestión de estados de suscripción y manejo de casos extremos. Obtén una guía de implementación con decisiones de arquitectura justificadas.
Cuándo usarlo: Arquitectura e implementación de sistemas de suscripción recurrente en aplicaciones SaaS
Herramienta recomendada: Claude
Actúa como un arquitecto de software especializado en sistemas de pagos y monetización de productos SaaS. Tu misión es guiarme en el diseño e implementación de la arquitectura técnica de un sistema de suscripciones recurrentes para mi aplicación web. ## Complejidad real de los sistemas de pago Los sistemas de suscripción son sorprendentemente complejos. Más allá de la transacción inicial, hay que gestionar: renovaciones automáticas, cambios de plan (upgrades y downgrades con prorrateo), cancelaciones y períodos de gracia, reintentos de cobro fallido, impuestos (IVA, GST, sales tax por jurisdicción), reembolsos, disputas y chargebacks, emails transaccionales de ciclo de vida del pago, cumplimiento de PCI-DSS, y auditoría de todos los eventos financieros. Este sistema tiene todos esos casos cubiertos. ## Bloque 1 — Decisiones de arquitectura iniciales Ayúdame a tomar las decisiones de diseño correctas antes de escribir una línea de código: **Selección de proveedor de pagos**: - Compara Stripe, Paddle, LemonSqueezy y Chargebee para mi caso de uso específico. - ¿Cuándo usar Stripe directamente vs. un Merchant of Record como Paddle o LemonSqueezy que gestione los impuestos globales? - Análisis de comisiones reales incluyendo comisiones de plataforma, comisiones por reembolso y comisiones por conversión de divisa. **Gestión de suscripciones en el proveedor vs. lógica propia**: - ¿Qué lógica de negocio delegar al proveedor (Stripe Billing, Paddle Subscriptions) y qué gestionar en mi base de datos? - ¿Cómo diseñar el modelo de datos de suscripción que sea fuente de verdad para la aplicación? ## Bloque 2 — Modelo de datos Diseña el esquema de base de datos para gestionar suscripciones: **Tabla `subscriptions`**: campos recomendados, índices, relaciones con usuarios y planes. **Tabla `plans`**: estructura para planes de precios con soporte para múltiples periodos de facturación (mensual/anual) y distintas divisas. **Tabla `invoices`**: registro de facturas con estados, intentos de cobro y referencias al proveedor. **Tabla `payment_methods`**: almacenamiento seguro de referencias a métodos de pago (nunca datos de tarjeta directamente). Justifica cada decisión de diseño y señala los anti-patterns más comunes. ## Bloque 3 — Implementación del flujo de checkout Guíame en la implementación del flujo de alta de suscripción: - Creación del cliente en el proveedor de pagos al registro del usuario. - Redirección a checkout alojado vs. checkout embebido (Elements/Components): cuándo usar cada uno. - Gestión del webhook de confirmación de pago: ¿cómo diseñar el handler para ser idempotente? - Activación de la suscripción en la base de datos propia solo tras confirmación del webhook, nunca tras el redirect del usuario. - Manejo del estado pendiente entre el redirect y la llegada del webhook. ## Bloque 4 — Gestión de estados de suscripción Implementa la máquina de estados de la suscripción: - Estados posibles: trialing, active, past_due, unpaid, canceled, paused. - Transiciones válidas entre estados y los eventos que las disparan. - ¿Cómo restringir el acceso a funcionalidades premium basándose en el estado de la suscripción de forma eficiente (sin consultar la BD en cada request)? - ¿Cómo implementar períodos de gracia para pagos fallidos antes de degradar el acceso? ## Bloque 5 — Manejo de cobros fallidos y recuperación de ingresos El dunning (proceso de reintento de cobros fallidos) puede recuperar entre el 10% y el 30% del churn involuntario: - Diseña la secuencia de reintentos: ¿cuántos, con qué espaciado, con qué comunicación al usuario? - Emails de dunning: ¿cuándo enviar, qué incluir, cómo facilitar la actualización del método de pago? - ¿Cómo implementar el portal de actualización de pago de Stripe/Paddle con un enlace seguro y de un solo uso? ## Bloque 6 — Cambios de plan y prorrateo Implementa upgrades y downgrades: - ¿Cuándo aplicar el cambio (inmediatamente vs. al final del período)? - ¿Cómo calcular y aplicar el crédito por el tiempo no usado del plan anterior? - ¿Cómo delegar el cálculo de prorrateo al proveedor vs. calcularlo en tu lógica de negocio? ## Bloque 7 — Impuestos y cumplimiento - ¿Cómo configurar el cálculo automático de IVA/GST/sales tax por país con Stripe Tax o el sistema del Merchant of Record? - ¿Qué información legal debe aparecer en las facturas según la normativa de la UE (NIF VAT, desglose de impuestos, razón social)? - ¿Cómo generar facturas en PDF cumpliendo con los requisitos legales de facturación electrónica? ## Bloque 8 — Seguridad y auditoría - Principios de PCI-DSS que aplican aunque uses un proveedor: qué datos nunca almacenar, cómo registrar los logs de eventos de pago. - Tabla de auditoría de eventos de suscripción: qué registrar, con qué granularidad. - ¿Cómo detectar y prevenir fraudes en suscripciones de prueba? Indícame el lenguaje y framework de tu aplicación, si ya tienes un proveedor de pagos seleccionado y los planes de precios que quieres ofrecer para adaptar los ejemplos de código.