Reaccionar a las suscripciones de SubscriptionConfigurator desde tu plugin

SubscriptionConfigurator avisa a otros plugins cuando una suscripción cambia de estado, usando la cola de eventos de FacturaScripts (WorkQueue). Así puedes, por ejemplo, dar de alta un acceso cuando alguien contrata, enviar un correo de bienvenida o cortar el servicio cuando cancela, sin tocar el código del plugin.

📣 1. Los eventos

EventoCuándo se emite
SubscriptionConfigurator.ActivatedPrimera factura cobrada de una suscripción: el cliente y la factura ya existen
SubscriptionConfigurator.RenewedCualquier factura cobrada posterior (renovación) de una suscripción ya activada
SubscriptionConfigurator.CanceledLa suscripción se ha cancelado en Stripe

Garantías:

  • Los eventos se emiten cuando todo lo que referencian ya está guardado (suscripción confirmada, cliente enlazado, factura creada).
  • Nunca más de una vez por cobro, aunque Stripe entregue sus avisos en distinto orden o los reintente.
  • Un fallo al emitir un evento nunca interrumpe el procesado del pago: solo queda registrado.

📦 2. Qué datos recibes

El valor del evento ($event->value) es el id de la suscripción del plugin (SubscriptionConfig). Los parámetros, con $event->param('nombre'):

ParámetroContenido
idfacturaId de la factura de cliente creada. No viene en Canceled
codclienteCódigo del cliente de FacturaScripts
idproducto_planId del producto del plan contratado
periodmonthly o annual
stripe_subscription_idId de la suscripción en Stripe (sub_...)
stripe_customer_idId del cliente en Stripe (cus_...)

🧩 3. Escuchar un evento desde tu plugin

Primero, en el Init::init() de tu plugin, registra tu Worker para el evento:

<?php
namespace FacturaScripts\Plugins\MiPlugin;

use FacturaScripts\Core\Template\InitClass;
use FacturaScripts\Core\WorkQueue;

final class Init extends InitClass
{
    public function init(): void
    {
        WorkQueue::addWorker('MiSuscripcionWorker', 'SubscriptionConfigurator.Activated');
        WorkQueue::addWorker('MiSuscripcionWorker', 'SubscriptionConfigurator.Canceled');
    }

    public function update(): void {}
    public function uninstall(): void {}
}

Después crea el Worker en Worker/MiSuscripcionWorker.php de tu plugin:

<?php
namespace FacturaScripts\Plugins\MiPlugin\Worker;

use FacturaScripts\Core\Model\WorkEvent;
use FacturaScripts\Core\Template\WorkerClass;

class MiSuscripcionWorker extends WorkerClass
{
    public function run(WorkEvent $event): bool
    {
        $idSuscripcion = $event->value;
        $codcliente = $event->param('codcliente');

        if ($event->name === 'SubscriptionConfigurator.Activated') {
            $idfactura = (int) $event->param('idfactura');
            // ... dar de alta el acceso del cliente $codcliente
        }

        if ($event->name === 'SubscriptionConfigurator.Canceled') {
            // ... retirar el acceso
        }

        return $this->done();
    }
}

Puntos a tener en cuenta:

  • addWorker() busca la clase Worker\<nombre> de tus plugins activos, así que basta con el nombre corto.
  • Un evento solo se guarda en la cola si hay algún Worker registrado para él. Sin Worker, el evento se descarta al emitirse y no queda rastro en work_events.
  • Se admiten comodines: 'SubscriptionConfigurator.*' recibe los tres eventos.
  • Devuelve $this->done() al terminar: así el evento sigue su camino hacia otros Workers que también lo escuchen. Con $this->stopPropagation() (devuelve false) los Workers posteriores no se ejecutan.
  • El evento no se reintenta. Se marca como realizado aunque tu Worker lance una excepción (FacturaScripts la anota en el registro bajo work-queue). Si tu trabajo puede fallar, captura tú el error y regístralo o reintenta por tu cuenta.
  • Aun así, haz tu Worker idempotente: comprueba si el acceso ya existía antes de crearlo, por si lo reenvías a mano.

⏱️ 4. Cuándo se ejecuta

Los eventos se encolan al cobrar y los procesa el cron de FacturaScripts, no el propio webhook. Si el cron no está configurado en tu servidor, tus Workers no se ejecutarán nunca; compruébalo en la documentación de FacturaScripts sobre el cron. Mientras no se procese, el evento aparece en la cola (tabla work_events).

🔌 5. Probarlo

  1. Haz una compra de prueba en modo test de Stripe.
  2. Comprueba que se ha creado un registro en work_events con el nombre del evento y el id de la suscripción.
  3. Ejecuta el cron (o espera a que lo haga) y verifica que tu Worker ha hecho su trabajo.

💡 Registra el Worker solo para los eventos que necesites, y mantén run() rápido: si tienes que hacer algo lento, déjalo en otra cola propia.

Cookies
Usamos cookies necesarias para el funcionamiento del sitio y cookies opcionales para recordar tus preferencias y mejorar tu experiencia. Puedes aceptarlas todas, rechazarlas o configurar tus preferencias

Soporte