Guía de instalación y configuración de SubscriptionConfigurator
SubscriptionConfigurator te permite vender suscripciones online: tus clientes arman su plan a medida en una página pública, pagan con tarjeta a través de Stripe, y FacturaScripts genera la factura ya cobrada automáticamente. Esta guía te lleva paso a paso desde la instalación hasta tu primera venta real.
🧰 Antes de empezar
Necesitas:
- ✅ Una cuenta de Stripe (puedes probar todo en modo test antes de activar cobros reales).
- ✅ La extensión PHP
sodiumhabilitada en tu servidor (la mayoría de los hostings ya la trae activada; se usa para guardar tus claves de Stripe de forma cifrada). - ✅ Los Impuestos de FacturaScripts bien configurados en tus productos: el IVA que lleva cada producto es el que se cobra y el que sale en la factura.
📦 1. Instalar el plugin
Sube el plugin desde Admin → Plugins → Subir plugin, selecciona el archivo .zip y actívalo. Al activarse, el plugin crea sus propias tablas y guarda su paleta de colores por defecto: no necesitas hacer nada más en la base de datos.
💡 Al actualizar a una versión nueva, pulsa Reconstruir en Admin → Plugins para que se apliquen los cambios internos del plugin.
🗂️ 2. Dar de alta tus productos
El configurador no inventa productos: usa los Productos normales de FacturaScripts. Para cada uno que quieras que aparezca en el configurador, ve a Admin → Productos del configurador y crea una fila indicando:
- 📌 Producto: el producto real de FacturaScripts (créalo primero en Productos si todavía no existe, con su precio sin IVA y su Impuesto).
- 📌 Sección: qué tipo de ítem es.
- Plan: la base de la suscripción; el cliente elige uno.
- Módulo: complemento que se suma al plan.
- Especialidad extra y Usuario extra: ítems que el cliente compra por unidades.
- Almacenamiento: bloque base y Almacenamiento: bloque extra: espacio incluido y bloques adicionales.
- Servicio de pago único: se cobra una sola vez, en el primer pago, y no se repite en las renovaciones.
- 📌 Si es un Plan: escribe una descripción corta (ej. "Incluye 2 usuarios") que se muestra debajo del nombre del plan en la página pública, y opcionalmente qué módulos incluye gratis.
- 📌 Si es un Módulo: opcionalmente, restríngelo a un plan concreto (por ejemplo, un módulo que solo se pueda comprar en el plan más caro).
- 📌 Elegible para descuento anual: es solo informativo y no cambia el precio. El pago anual (compromiso de doce meses) se cobra con descuento, diez de los doce meses, para todos los productos recurrentes del catálogo.
Repite esto por cada plan, módulo y extra que quieras ofrecer. Si más adelante quieres dejar de vender algo, desactívalo en su fila en lugar de borrarlo: las suscripciones que ya lo contrataron siguen renovándose bien.
💳 3. Configurar Stripe
Ve a Admin → Stripe y carga:
- 🔑 Clave publicable (pk_test_... o pk_live_...).
- 🔒 Clave secreta (sk_test_... o sk_live_...), que se guarda cifrada.
Guarda, y después pulsa "Sincronizar precios con Stripe". Esto crea automáticamente, en tu cuenta de Stripe, un Precio por cada producto que diste de alta en el paso anterior: no tienes que crear nada manualmente en el panel de Stripe.
💡 Usa siempre el par de claves del mismo modo (test con test, live con live). Prueba primero en modo test.
🔄 Si cambias un precio o añades productos
Stripe no permite modificar el importe de un Precio ya creado. Por eso, cuando cambias el precio de un producto en FacturaScripts, vuelves a pulsar "Sincronizar precios con Stripe" y el plugin crea un Precio nuevo y archiva el anterior. Los productos nuevos se crean en la misma pasada, y si algún Precio ha desaparecido de tu cuenta de Stripe, también se vuelve a crear. Al terminar verás un resumen de lo que se ha creado, actualizado o recreado.
⚠️ Las suscripciones ya activas siguen cobrando el precio con el que se contrataron; el cambio se aplica a las nuevas contrataciones.
🔔 4. Configurar el webhook de Stripe
Para que FacturaScripts se entere cuando alguien paga o cancela, Stripe necesita avisarle. En el panel de Stripe:
- Ve a Webhooks (dentro de "Developers" o "Workbench", según la versión del panel).
- Añade un endpoint con esta URL:
https://tu-dominio.com/RUTA-DE-TU-FACTURASCRIPTS/WebhookStripe - Selecciona estos tres eventos:
checkout.session.completed,invoice.payment_succeededycustomer.subscription.deleted. - Copia el "Signing secret" (whsec_...) que te muestra Stripe.
- Pégalo en el campo "Firma del webhook" de Admin → Stripe, y guarda.
En esa misma pantalla, la pestaña Eventos de webhook muestra cada aviso recibido y si se procesó bien o con error: es el primer sitio donde mirar si una venta no genera su factura.
⚠️ Si estás probando en local (localhost), Stripe no puede alcanzar esa URL desde internet. Usa la Stripe CLI (stripe listen --forward-to http://localhost/.../WebhookStripe) mientras haces pruebas.
🎨 5. Personalizar la apariencia
Ve al Panel de control de FacturaScripts (Admin → Panel de control) y busca la pestaña "Configurador de suscripción". Ahí puedes cambiar:
- ✏️ El nombre de tu marca y el título/subtítulo de la página pública.
- 🎨 Los tres colores principales de la página, para que combinen con tu identidad. Vienen con una paleta por defecto ya cargada.
💡 El logo que se muestra es el mismo que ya tienes cargado en Ajustes → Empresa: no hace falta subirlo dos veces.
🧪 6. Probar una compra
Con las claves en modo test y el webhook configurado, abre tu página de venta, arma un plan y paga con la tarjeta de prueba de Stripe 4242 4242 4242 4242 (cualquier fecha futura y cualquier CVC). Comprueba que en Admin → Suscripciones aparece la suscripción y que en Ventas → Facturas hay una factura cobrada. Cuando todo funcione, cambia a las claves live y repite el paso 3 y el 4 con ellas.
🚀 7. Publicar tu página de venta
Tu página pública ya está lista en: https://tu-dominio.com/RUTA-DE-TU-FACTURASCRIPTS/PublicSubscriptionConfigurator
Puedes enlazarla desde tu web, tus redes o tus campañas: no requiere que el visitante inicie sesión ni se registre.
✅ 8. Qué pasa cuando alguien compra
- 🛒 El visitante arma su plan, ve el precio actualizado al instante, y hace clic en "Suscribirme y pagar".
- 💳 Se le redirige a una página de pago de Stripe, donde también completa su NIF/CIF y dirección de facturación. Paga el precio más el IVA de cada producto.
- 🧾 Al pagar, Stripe avisa a FacturaScripts, que automáticamente crea (o reutiliza) el Cliente con esos datos fiscales, genera una Factura real con cada ítem elegido y su IVA, y la marca como cobrada. El total de la factura coincide con lo cobrado; si alguna vez no coincide, el plugin deja un aviso en el registro para que lo revises.
- 🔁 Cada renovación mensual o anual genera su factura sola, sin que tengas que hacer nada.
- 🛑 Si la suscripción se cancela en Stripe, el plugin la marca como cancelada.
📊 9. Hacer seguimiento
En Admin → Suscripciones puedes ver de un vistazo qué suscripciones están activas, quién las contrató y qué eligió cada cliente, sin tener que cruzar tus facturas con el panel de Stripe.
❓ Problemas habituales
- Una venta no genera factura: mira la pestaña Eventos de webhook en Admin → Stripe. Si no aparece ningún evento, el endpoint o la firma del webhook están mal; si aparece con error, el mensaje te dice el motivo.
- Error al sincronizar un producto ("No such price"): ese Precio ya no existe en tu cuenta de Stripe (por ejemplo, porque cambiaste de cuenta o de modo test/live). Pulsa de nuevo Sincronizar precios con Stripe: se recrea solo.
- El cliente ve la página sin estilo o con colores raros: revisa los tres colores en el Panel de control, pestaña "Configurador de suscripción".