app-padel/docs/roadmap/FASE-04.md

Fase 4: Pagos y Monetización

Estado: ✅ COMPLETADA

✅ Tareas completadas:

4.1.1: Integración de MercadoPago

• SDK de MercadoPago instalado y configurado
• Crear preferencias de pago
• Webhooks para notificaciones de pago
• Procesar pagos completados
• Reembolsos (refunds)
• Cancelación de pagos pendientes

4.1.2: Gestión de Transacciones

• Historial de pagos del usuario
• Estados de pago (PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED, CANCELLED)
• Comprobantes/facturas automáticas
• Metadata de pagos (método, cuotas)

4.2.1: Sistema de Bonos

• Tipos de bonos (5, 10, 30 clases)
• Compra de bonos online (integración MP)
• Descuento automático al usar bono
• Expiración de bonos configurable
• Historial de uso de bonos
• Verificación automática de expirados

4.2.2: Suscripciones/Membresías

• Planes: Básico, Premium, Anual VIP
• Beneficios por plan (descuentos, reservas gratis, prioridad)
• Cobro recurrente vía MercadoPago
• Estados: PENDING, ACTIVE, PAUSED, CANCELLED, EXPIRED
• Cambio de método de pago
• Aplicación automática de beneficios en reservas

4.3.1: Gestión de Profesores

• Perfil de coaches (bio, especialidades, certificaciones)
• Horarios disponibles por coach
• Tarifas por clase/tipo
• Sistema de reseñas y rating

4.3.2: Reserva de Clases

• Catálogo de clases disponibles
• Tipos: Individual, Grupal, Clínica
• Reserva con pago integrado (MP)
• Control de cupos
• Historial de clases tomadas
• Marcado de asistencia

---

💳 Integración MercadoPago

Flujo de Pago

1. Crear Preferencia → Backend crea preferencia MP con items
2. Redirigir a MP → Frontend redirige a init_point
3. Usuario paga → En MP con tarjeta/efectivo/transferencia
4. Webhook MP → Notifica a backend el resultado
5. Actualizar estado → Backend actualiza payment y entidad relacionada

Estados de Pago

Estado	Descripción
PENDING	Preferencia creada, esperando pago
PROCESSING	Pago en proceso
COMPLETED	Pago aprobado
FAILED	Pago rechazado
REFUNDED	Reembolsado
CANCELLED	Cancelado por usuario

---

🎟️ Sistema de Bonos

Tipos de Bonos

Nombre	Reservas	Precio	Validez
Pack 5 Clases	5	$90	90 días
Pack 10 Clases	10	$160	180 días
Pack Mensual	30	$400	30 días

Reglas

• Un bono = Una reserva completa (1 hora)
• No se puede usar parcialmente
• Un booking solo puede tener un bono
• FIFO al usar (el que expira primero)

---

💎 Suscripciones

Planes Disponibles

Plan	Precio/Mes	Descuento	Gratis/Mes	Prioridad
Básico	$150	10%	2	No
Premium	$250	20%	5	Sí
Anual VIP	$25000/año	30%	10	Sí

Beneficios Automáticos

• Descuento en todas las reservas
• Reservas gratis mensuales (contador)
• Prioridad en reservas (primeros en cola)
• Descuento en torneos

---

👨‍🏫 Sistema de Clases

Tipos de Clase

Tipo	Máx. Alumnos	Duración	Precio/persona
Individual	1	60 min	$50
Grupal	2-4	60 min	$35
Clínica	5-16	90 min	$20

Proceso

1. Ver catálogo de clases
2. Seleccionar clase y ver sesiones disponibles
3. Inscribirse y pagar vía MercadoPago
4. Confirmación automática al completar pago
5. Asistencia marcada por el coach

---

🔌 Endpoints de Pagos

POST   /api/v1/payments/preference        - Crear preferencia MP
GET    /api/v1/payments/my-payments       - Mis pagos
GET    /api/v1/payments/:id               - Ver pago
POST   /api/v1/payments/webhook           - Webhook MP (público)
POST   /api/v1/payments/:id/refund        - Reembolsar (admin)
POST   /api/v1/payments/:id/cancel        - Cancelar pago

🔌 Endpoints de Bonos

GET    /api/v1/bonus-packs                - Listar packs disponibles
POST   /api/v1/bonus-packs                - Crear pack (admin)
POST   /api/v1/bonuses/purchase           - Comprar bono
GET    /api/v1/bonuses/my-bonuses         - Mis bonos
GET    /api/v1/bonuses/available          - Bonos disponibles para usar
POST   /api/v1/bonuses/:id/use            - Usar bono específico
POST   /api/v1/bonuses/use-auto           - Usar bono automático

🔌 Endpoints de Suscripciones

GET    /api/v1/subscription-plans         - Listar planes
POST   /api/v1/subscription-plans         - Crear plan (admin)
POST   /api/v1/subscriptions              - Crear suscripción
GET    /api/v1/subscriptions/my-subscription - Mi suscripción
GET    /api/v1/subscriptions/benefits     - Ver mis beneficios
PUT    /api/v1/subscriptions/:id/cancel   - Cancelar
PUT    /api/v1/subscriptions/:id/pause    - Pausar
PUT    /api/v1/subscriptions/:id/resume   - Reanudar
POST   /api/v1/subscriptions/webhook      - Webhook MP

🔌 Endpoints de Clases

POST   /api/v1/coaches/register           - Registrarme como coach
GET    /api/v1/coaches                    - Listar coaches
GET    /api/v1/coaches/:id                - Ver coach
POST   /api/v1/coaches/:id/reviews        - Dejar reseña
GET    /api/v1/classes                    - Listar clases
POST   /api/v1/classes                    - Crear clase (coach)
POST   /api/v1/classes/:id/sessions       - Programar sesión
POST   /api/v1/class-enrollments          - Inscribirme
GET    /api/v1/class-enrollments/my       - Mis inscripciones
PUT    /api/v1/class-enrollments/:id/attend - Marcar asistencia

---

🚀 Cómo probar pagos

Configurar credenciales MercadoPago

# .env
MERCADOPAGO_ACCESS_TOKEN=TEST-xxxxxxxx
MERCADOPAGO_PUBLIC_KEY=TEST-yyyyyyyy

Crear preferencia de pago

curl -X POST http://localhost:3000/api/v1/payments/preference \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BOOKING",
    "referenceId": "booking-id",
    "title": "Reserva Cancha 1",
    "description": "Reserva para el 15/02/2024",
    "amount": 2500
  }'

---

📁 Archivos creados en esta fase

backend/src/
├── config/
│   └── mercadopago.ts           # Configuración MP
├── services/
│   ├── payment.service.ts       # Pagos con MP
│   ├── bonusPack.service.ts     # Packs de bonos
│   ├── userBonus.service.ts     # Bonos de usuarios
│   ├── subscriptionPlan.service.ts  # Planes
│   ├── subscription.service.ts  # Suscripciones
│   ├── coach.service.ts         # Coaches
│   ├── class.service.ts         # Clases
│   └── classEnrollment.service.ts   # Inscripciones
├── controllers/
│   ├── payment.controller.ts
│   ├── bonusPack.controller.ts
│   ├── userBonus.controller.ts
│   ├── subscriptionPlan.controller.ts
│   ├── subscription.controller.ts
│   ├── coach.controller.ts
│   ├── class.controller.ts
│   └── classEnrollment.controller.ts
├── routes/
│   ├── payment.routes.ts
│   ├── bonus.routes.ts
│   ├── subscription.routes.ts
│   ├── coach.routes.ts
│   ├── class.routes.ts
│   └── classEnrollment.routes.ts
└── validators/
    ├── payment.validator.ts
    ├── bonus.validator.ts
    ├── subscription.validator.ts
    └── class.validator.ts

---

🎯 Datos de prueba

Entidad	Datos
Bonus Packs	Pack 5, Pack 10, Pack Mensual
Planes	Básico ($150), Premium ($250), Anual VIP ($25000)
Coach	Admin verificado como coach
Clases	Individual, Pareja, Clínica de Volea

---

📝 Notas

• MercadoPago en modo sandbox para desarrollo
• Webhooks configurables en dashboard de MP
• Requiere cuenta de MP para producción
• Beneficios de suscripción aplicados automáticamente

---

Completada el: 2026-01-31