Referidos

El programa de referidos le da a cada usuario un enlace. Cuando alguien se registra después de seguirlo, las dos cuentas quedan ligadas y al que refirió se le acredita una recompensa fija; cada vez que la cuenta referida paga una factura de suscripción, se le acredita un porcentaje. Las recompensas son números que el kit guarda y muestra. Nada las paga: esa parte te toca construirla.

Enciéndelo

Cinco variables de entorno, leídas por config/features.php bajo referrals. Ninguna está en .env.example, así que agrega las que necesites.

FEATURE_REFERRALS_ENABLED=true
FEATURE_REFERRALS_REGISTRATION_REWARD=10
FEATURE_REFERRALS_SUBSCRIPTION_REWARD_PERCENT=10
FEATURE_REFERRALS_CURRENCY=mxn
FEATURE_REFERRALS_COOKIE_DAYS=30

La recompensa de suscripción necesita planes y el webhook de Stripe, porque se crea a partir de invoice.paid. Mira Enciende los planes y la facturación. La recompensa de registro no necesita nada más.

El enlace de referido

https://your-project.test/?referrer=K7QP2XM4

El código es users.referral_code: ocho caracteres aleatorios en mayúsculas, único, creado la primera vez que el usuario abre la página de referidos o que tu código llama a $user->getOrCreateReferralCode(). $user->referralUrl() construye el enlace de arriba.

El parámetro referrer se lee en cualquier página, no sólo en la de inicio. El middleware App\Http\Middleware\CaptureReferralCode corre en cada petición web y, en un GET normal que no sea una llamada de Livewire ni JSON, le entrega la petición a App\Classes\Referrals:

1. El código se recorta y se pasa a mayúsculas. Si ningún usuario tiene ese código, no pasa nada.
2. Se guarda en la sesión bajo referrals.referrer_code, y en una cookie llamada referrer_code que dura cookie_days días.
3. En visitas posteriores sin código en la sesión, la cookie lo restaura y se vuelve a encolar, así que la ventana se reinicia cada vez que el visitante regresa.

Un visitante que sigue el enlace hoy y se registra dentro de la ventana de la cookie sigue quedando atribuido. Un código que llega al sitio con la bandera apagada se ignora, no se guarda.

Cuando la persona referida se registra

App\Observers\UserObserver::created() llama a $user->registerReferredUser() por cada usuario nuevo, sin importar cómo se creó. Lee el código de la sesión, luego de la cookie, encuentra a quien refirió y:

• No hace nada si no hay código, el código no coincide con ningún usuario, o quien refirió es el propio usuario nuevo.
• Crea una fila en referrals: referrer_id, referred_id, el code usado y registered_at. Un usuario puede ser referido una sola vez; referred_id es único.
• Crea la recompensa de registro cuando registration_reward es mayor a cero: una fila en referral_rewards con type registration, el amount configurado, la currency configurada y el id del usuario referido como source_id, para que el mismo registro nunca se recompense dos veces.

Para la persona referida nada cambia: ni descuento, ni crédito, ni mención en pantalla.

Cuando la persona referida paga

Cada evento invoice.paid que Stripe manda por una suscripción llega al controlador de webhooks del paquete. Cuando el amount_paid de la factura es mayor a cero, despacha WeblaborMx\BillingCore\Events\SubscriptionPaid con el importe en unidades mayores, la moneda de la factura, el id de la factura y el id de la suscripción. App\Listeners\RecordSubscriptionPayment escucha, ignora las cuentas que no son de usuario y llama a $user->recordPaidSubscriptionReward($amount, $currency, $invoiceId):

• No se registra nada si la bandera está apagada, el importe es cero, el usuario no fue referido o subscription_reward_percent es cero.
• En otro caso, una fila en referral_rewards con type subscription, amount = importe de la factura × porcentaje ÷ 100 redondeado a dos decimales, source_amount = el importe de la factura, percentage = el porcentaje, currency = la moneda de la factura en minúsculas y source_id = el id de la factura en Stripe.

El par type + source_id es único por referido, así que un webhook entregado dos veces registra una sola recompensa. Cuenta cada factura: el primer pago, cada renovación y las facturas que generan los complementos de la suscripción. Los planes gratis y las pruebas no pagan nada, así que no acreditan nada. La recompensa se acredita en el momento en que llega el webhook; un webhook ausente o mal configurado significa que no habrá recompensas de suscripción.

Cuánto, y en qué moneda

La recompensa de registro siempre está en FEATURE_REFERRALS_CURRENCY. La recompensa de suscripción está en la moneda de la factura, sin importar en qué se cotizó el plan. Quien refirió cuentas que pagan en dos monedas tiene, por lo tanto, dos totales, y el kit nunca convierte uno en el otro: rewardTotals() agrupa por moneda y cada pantalla lista una cifra por moneda, con formato $ seguido del importe y el código, por ejemplo $150.00 MXN.

Cómo se guarda

No hay columna de saldo, ni tabla de pagos, ni cargos. Los totales que ve un usuario son SUM(amount) sobre sus recompensas, agrupadas por moneda, calculados en cada carga de página. Por eso la pantalla habla de "dinero virtual". Cuando construyas los pagos, agrega tu propia tabla que registre lo pagado y réstalo de estos totales.

Las piezas que llamas desde código:

Lo que ve el usuario

Referencias, con un ícono de regalo, aparece en la barra lateral de la cuenta y abre /account/referrals. La página tiene tres tarjetas:

• "Recomienda y gana": la recompensa de registro y el porcentaje de suscripción tal como están configurados, el total de dinero virtual generado por moneda y cuántos usuarios se registraron con el enlace.
• "Tu enlace de referencia": el enlace en un campo de sólo lectura y un botón Copiar enlace, con la nota de que un visitante que se registre después sigue quedando asociado durante varios días.
• "Usuarios registrados con tu enlace": una fila por usuario referido con nombre y correo, la fecha de registro y lo que ese usuario generó, por moneda. Una cuenta referida eliminada se muestra como usuario eliminado.

La persona referida no ve nada sobre el referido en ningún lado.

Lo que ve el administrador

El dashboard de administración, /admin, ofrece Suscripciones por referencias en su selector de métrica mientras la bandera está encendida. Dibuja dos series en el rango de fechas elegido: nuevas inscripciones por referencia, a partir de referrals.registered_at, y suscripciones de referencia pagadas, contando las recompensas subscription por la fecha en que se crearon.

Eso es todo. No hay recurso de administración para referidos ni recompensas, el formulario de usuario no muestra el código de referido y nada permite a un administrador editar o cancelar una recompensa. Las correcciones se hacen en la base de datos o con código que agregues.