michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-023-programa-referidos.md

MCH-023: Programa de Referidos

Metadata

• Codigo: MCH-023
• Fase: 6 - Crecimiento
• Prioridad: P2
• Estado: Completado
• Fecha completado: 2026-01-10

Descripcion

Programa de referidos para crecimiento organico: codigos de referencia unicos, beneficios para referidor y referido, tracking de conversiones, y recompensas automaticas.

Objetivos

1. Codigos de referido unicos
2. Beneficios para ambas partes
3. Tracking de conversiones
4. Recompensas automaticas
5. Dashboard de referidos

Alcance

Incluido

• Codigo unico por usuario
• Link compartible
• Beneficio: 1 mes gratis (referidor)
• Beneficio: 50% descuento primer mes (referido)
• Dashboard con estadisticas
• Notificaciones de conversion

Excluido

• Comisiones en efectivo
• Multinivel (referidos de referidos)
• Programa de afiliados formal

Mecanica del Programa

Beneficios

Rol	Beneficio	Condicion
Referidor	1 mes gratis de suscripcion	Por cada referido que pague
Referido	50% descuento primer mes	Al registrarse con codigo

Flujo de Referido

1. Usuario A tiene codigo "TIENDAJUAN"
2. Comparte link: michangarrito.com/r/TIENDAJUAN
3. Usuario B se registra con codigo
4. Usuario B obtiene 50% descuento
5. Usuario B paga primer mes
6. Usuario A recibe notificacion
7. Usuario A obtiene 1 mes gratis acumulado

Modelo de Datos

Tablas

referral_codes

• id, tenant_id, code (unique)
• created_at, active

referrals

• id, referrer_tenant_id, referred_tenant_id
• code_used, status (pending/converted/expired)
• converted_at, reward_applied_at

referral_rewards

• id, tenant_id, type (free_month)
• months_earned, months_used
• expires_at

Endpoints API

Metodo	Endpoint	Descripcion
GET	/referrals/my-code	Mi codigo
POST	/referrals/generate-code	Generar nuevo codigo
GET	/referrals/stats	Estadisticas
GET	/referrals/list	Mis referidos
POST	/referrals/apply-code	Aplicar codigo (registro)
GET	/referrals/rewards	Mis recompensas

Estados del Referido

pending ──► converted ──► rewarded
    │
    └──► expired (si no paga en 30 dias)

Estado	Descripcion
pending	Referido registrado, no ha pagado
converted	Referido pago primer mes
rewarded	Recompensa aplicada al referidor
expired	Referido no pago en tiempo

UI Components

ShareReferralCard

┌─────────────────────────────────┐
│  Invita amigos y gana          │
│                                 │
│  Tu codigo: TIENDAJUAN         │
│                                 │
│  [Copiar]  [Compartir WhatsApp] │
│                                 │
│  Por cada amigo que se suscriba │
│  ganas 1 mes gratis!           │
└─────────────────────────────────┘

ReferralStats

┌─────────────────────────────────┐
│  Tus Referidos                 │
├─────────────────────────────────┤
│  👥 Invitados: 8               │
│  ✅ Convertidos: 3             │
│  🎁 Meses ganados: 3           │
│  📅 Meses disponibles: 2       │
└─────────────────────────────────┘

ReferralList

• Tabla de referidos
• Nombre, fecha, estado
• Recompensa aplicada

Notificaciones

Referido se Registra

[Push al referidor]
"🎉 Juan se registro con tu codigo!
Te avisaremos cuando active su suscripcion."

Referido Paga

[Push + WhatsApp al referidor]
"🎁 Ganaste 1 mes gratis!
Juan activo su suscripcion.
Ya tienes 3 meses acumulados."

Integracion con Suscripciones

// Al procesar pago de suscripcion
async function processSubscriptionPayment(tenant, payment) {
  // Verificar si tiene meses gratis disponibles
  const rewards = await getReferralRewards(tenant.id);

  if (rewards.months_available > 0) {
    // Usar mes gratis en lugar de cobrar
    await useReferralMonth(tenant.id);
    return { charged: false, used_referral: true };
  }

  // Cobrar normalmente
  return chargeSubscription(tenant, payment);
}

Entregables

Entregable	Estado	Archivo
referrals.module	Completado	apps/backend/src/modules/referrals/
DDL referrals	Completado	database/schemas/13-referrals.sql
Referrals Page	Completado	apps/frontend/src/pages/Referrals.tsx
Referrals API	Completado	apps/frontend/src/lib/api.ts
Deep linking	Pendiente	Mobile config

Dependencias

Depende de

• MCH-018 (Suscripciones)
• MCH-017 (Notificaciones)

Bloquea a

• Ninguno

Criterios de Aceptacion

• Codigo unico se genera
• Link compartible funciona
• Descuento se aplica al referido
• Mes gratis se acredita al referidor
• Dashboard muestra estadisticas
• Notificaciones se envian (requiere integracion con MCH-017)

Configuracion

{
  referrals: {
    enabled: true,
    referrer_reward: { type: 'free_month', months: 1 },
    referred_discount: { percent: 50, months: 1 },
    code_prefix: 'MCH', // MCH-XXXXX
    expiry_days: 30 // dias para que referido pague
  }
}

---

Ultima actualizacion: 2026-01-10