Plugin de Suscripciones de Discourse

[SubStrider]

[Guía] Cómo configurar suscripciones de Discourse con tablas de precios de Stripe (y errores comunes)

Hola a todos,

Después de un largo proceso de solución de problemas, quería compartir una guía definitiva para configurar el plugin oficial discourse-subscriptions utilizando el método moderno de Tabla de precios de Stripe. Este enfoque es potente, pero tiene algunos pasos críticos que no son inmediatamente obvios y pueden generar errores como webhooks fallidos (404 Not Found) o que los usuarios no se agreguen a grupos después de un pago exitoso.

Aquí está el proceso paso a paso que se confirma que funciona.

---

Parte 1: Configuración de Stripe

Este proceso utiliza Stripe como la “fuente de verdad” para todos los productos y precios.

1. Crea tus productos y precios

• En tu Panel de Stripe, asegúrate de estar en Modo en vivo.
• Ve a Productos > Catálogo de productos.
• Crea primero tus productos principales (por ejemplo, “Membresía Premium”, “Acceso VIP”).
• Debajo de cada producto, crea todos los precios asociados (por ejemplo, XX / mes, XXX / año).

2. El paso CRUCIAL de metadatos Para que el plugin agregue automáticamente a los usuarios a un grupo, debes agregar metadatos específicos a cada objeto de Precio que crees. La interfaz de usuario del panel de Stripe puede dificultar su localización.

• Al crear un nuevo precio (o si puedes encontrar la opción “Editar precio”), debes agregar metadatos. Es posible que debas hacer clic en “Opciones adicionales” durante la creación del precio para revelar los campos de metadatos.
• Haz clic en + Agregar metadatos e introduce lo siguiente:
  • CLAVE: group_name
  • VALOR: El slug/identificador único y seguro para URL del grupo de Discourse, no su nombre completo.

Ejemplo:

• Si el nombre completo de tu grupo de Discourse es “Enclave Plus”, su slug probablemente sea EnclavePlus.
• Debes usar EnclavePlus como valor. Usar "Enclave Plus" con un espacio fallará.

• Debes repetir esto para cada plan de precios que desees vincular a un grupo.

3. Crea tu tabla de precios de Stripe

• Ve a Productos > Tablas de precios.
• Crea una nueva tabla y agrega los precios que acabas de configurar.
• Después de publicar la tabla, haz clic en el botón “Copiar código” para obtener tu ID de tabla de precios (comienza con prctbl_...).

4. Configura el endpoint del webhook (La solución al error 404) Este es el punto de fallo más común.

• Ve a Desarrolladores > Webhooks y haz clic en + Agregar endpoint.
• La URL del endpoint debe tener el siguiente formato: https://tu-sitio-discourse.com/s/hooks
  • Nota: La ruta correcta es /s/hooks, no /s/stripe/webhook.
• Para Eventos a enviar, agrega como mínimo:
  • checkout.session.completed
  • customer.subscription.deleted
• Crea el endpoint y copia el Secreto de firma (comienza con whsec_...).

---

Parte 2: Configuración de Discourse

Ahora, configuremos el plugin para usar todo lo que configuraste en Stripe.

1. Introduce las claves API y el ID de la tabla de precios

• Ve a Admin > Ajustes y busca discourse subscriptions.
• Introduce tus claves de Stripe en vivo:
  • discourse subscriptions public key (pk_live_...)
  • discourse subscriptions secret key (sk_live_...)
  • discourse subscriptions webhook secret (whsec_...)
• Habilita el modo de tabla de precios:
  • Marca la casilla discourse subscriptions pricing table enabled.
  • Pega tu ID prctbl_... en el campo discourse subscriptions pricing table id.

2. Vincula productos de Stripe a grupos de Discourse Incluso con una tabla de precios, necesitas decirle a Discourse qué grupo pertenece a qué producto.

• Ve a Admin > Plugins > Subscriptions y haz clic en la pestaña Products.
• Haz clic en Create New Product.
• Introduce un Product Name que coincida exactamente con el Product Name en Stripe (por ejemplo, Enclave Plus).
• Guarda el producto. En la página del producto, desplázate hacia abajo y haz clic en Add New Plan.
• Este plan es solo un “puente”. El único campo crítico es User Group.
  • Plan Nickname: Enclave Plus Group Link (o cualquier cosa para tu referencia).
  • User Group: Selecciona el grupo de Discourse correcto del menú desplegable.
  • Los otros campos (Amount, Interval) se pueden dejar por defecto, ya que se ignorarán.
• Guarda el plan. Repite esto para todos tus diferentes productos.

---

Resumen de solución de problemas

• Problema: Los webhooks fallan con un error 404 Not Found.
  • Solución: La URL del endpoint en Stripe es incorrecta. Debe ser https://tu-sitio-discourse.com/s/hooks.
• Problema: El webhook es exitoso (200 OK) y el pago aparece en el perfil de facturación del usuario, pero no se agrega al grupo.
  • Solución: Tus metadatos son incorrectos. Comprueba tres cosas:
    1. Los metadatos deben estar en el objeto Stripe Price, no en el objeto Product.
    2. La CLAVE de metadatos debe ser exactamente group_name.
    3. El VALOR de metadatos debe ser el slug/identificador único del grupo (por ejemplo, EnclavePlus), no su nombre completo con espacios.

Espero que esta guía ahorre a otros el tiempo y la frustración de esta configuración compleja pero muy potente.