app-padel/docs/API.md

📚 API Documentation - App Canchas de Pádel

Documentación completa de la API REST para la aplicación de gestión de canchas de pádel.

📖 Índice

• Introducción
• Autenticación
• Base URL
• Formatos de Respuesta
• Códigos de Error
• Módulos
  • Autenticación
  • Usuarios
  • Canchas
  • Reservas
  • Partidos
  • Torneos
  • Ligas
  • Rankings
  • Pagos
  • Suscripciones
  • Amigos
  • Notificaciones
  • Wall of Fame
  • Logros
  • Analytics

---

Introducción

La API de App Canchas de Pádel proporciona endpoints RESTful para gestionar todas las operaciones de una aplicación de canchas de pádel, incluyendo reservas, torneos, ligas, pagos y más.

Características principales:

• ✅ Más de 150 endpoints RESTful
• ✅ Autenticación JWT segura
• ✅ Rate limiting integrado
• ✅ Validación de datos con Zod
• ✅ Soporte para múltiples roles de usuario
• ✅ Integración con MercadoPago

---

Autenticación

La API utiliza JSON Web Tokens (JWT) para la autenticación.

Header de Autenticación

Authorization: Bearer <token_jwt>

Tipos de Tokens

Token	Duración	Uso
Access Token	7 días	Peticiones autenticadas
Refresh Token	30 días	Renovación de access token

Roles de Usuario

enum UserRole {
  PLAYER = 'PLAYER',           // Jugador estándar
  ADMIN = 'ADMIN',             // Administrador del club
  SUPERADMIN = 'SUPERADMIN'    // Super administrador
}

Niveles de Jugador

enum PlayerLevel {
  BEGINNER = 'BEGINNER',           // 1.0 - 2.0
  ELEMENTARY = 'ELEMENTARY',       // 2.5 - 3.5
  INTERMEDIATE = 'INTERMEDIATE',   // 4.0 - 5.0
  ADVANCED = 'ADVANCED',           // 5.5 - 6.5
  COMPETITION = 'COMPETITION',     // 7.0 - 8.0
  PROFESSIONAL = 'PROFESSIONAL'    // 8.5 - 10.0
}

---

Base URL

Desarrollo:  http://localhost:3000/api/v1
Producción:  https://api.tudominio.com/api/v1

---

Formatos de Respuesta

Respuesta Exitosa

{
  "success": true,
  "data": { ... },
  "message": "Operación exitosa"
}

Respuesta de Lista (Paginada)

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "totalPages": 10
    }
  }
}

Respuesta de Error

{
  "success": false,
  "message": "Descripción del error",
  "errors": [
    { "field": "email", "message": "Email inválido" }
  ]
}

---

Códigos de Error

Códigos HTTP

Código	Descripción	Uso
200	OK	Petición exitosa
201	Created	Recurso creado
400	Bad Request	Datos inválidos
401	Unauthorized	No autenticado
403	Forbidden	Sin permisos
404	Not Found	Recurso no encontrado
409	Conflict	Conflicto de datos
422	Unprocessable Entity	Validación fallida
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Error del servidor

Errores Comunes

// 401 - Token expirado
{
  "success": false,
  "message": "Token inválido o expirado"
}

// 403 - Sin permisos
{
  "success": false,
  "message": "No tienes permisos para realizar esta acción"
}

// 404 - Recurso no encontrado
{
  "success": false,
  "message": "Usuario no encontrado"
}

// 429 - Rate limit
{
  "success": false,
  "message": "Demasiadas peticiones, por favor intenta más tarde"
}

---

Módulo: Autenticación

Base path: /auth

Método	Endpoint	Auth	Descripción
POST	/auth/register	❌	Registrar nuevo usuario
POST	/auth/login	❌	Iniciar sesión
POST	/auth/refresh	❌	Renovar access token
POST	/auth/logout	❌	Cerrar sesión
GET	/auth/me	✅	Obtener perfil actual

Ejemplos

Registro:

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "usuario@ejemplo.com",
  "password": "password123",
  "firstName": "Juan",
  "lastName": "Pérez",
  "phone": "+5491123456789"
}

Login:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "usuario@ejemplo.com",
  "password": "password123"
}

Respuesta exitosa:

{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "email": "usuario@ejemplo.com",
      "firstName": "Juan",
      "lastName": "Pérez",
      "role": "PLAYER",
      "level": "INTERMEDIATE"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

---

Módulo: Usuarios

Base path: /users

Método	Endpoint	Auth	Descripción
GET	/users/me	✅	Mi perfil completo
PUT	/users/me	✅	Actualizar mi perfil
GET	/users/search	✅	Buscar usuarios
GET	/users/:id	✅	Perfil público de usuario
GET	/users/:id/level-history	✅	Historial de niveles
PUT	/users/:id/level	🔐	Cambiar nivel (admin)

Ejemplo: Actualizar Perfil

PUT /api/v1/users/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "Juan",
  "lastName": "Pérez",
  "phone": "+5491123456789",
  "level": "ADVANCED",
  "handPreference": "RIGHT",
  "positionPreference": "DRIVE"
}

---

Módulo: Canchas

Base path: /courts

Método	Endpoint	Auth	Descripción
GET	/courts	❌	Listar todas las canchas
GET	/courts/:id	❌	Detalle de cancha
GET	/courts/:id/availability	❌	Disponibilidad de cancha
POST	/courts	🔐	Crear cancha
PUT	/courts/:id	🔐	Actualizar cancha
DELETE	/courts/:id	🔐	Eliminar cancha

Ejemplo: Crear Cancha

POST /api/v1/courts
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Cancha 1",
  "type": "PANORAMIC",
  "pricePerHour": 15000,
  "openingTime": "08:00",
  "closingTime": "23:00",
  "isIndoor": true,
  "hasLighting": true
}

Tipos de Cancha

• PANORAMIC - Cancha panorámica (cristal)
• OUTDOOR - Cancha exterior
• INDOOR - Cancha techada
• SINGLE - Cancha individual

---

Módulo: Reservas

Base path: /bookings

Método	Endpoint	Auth	Descripción
POST	/bookings	✅	Crear reserva
GET	/bookings	🔐	Listar todas las reservas
GET	/bookings/my-bookings	✅	Mis reservas
GET	/bookings/price-preview	✅	Calcular precio
GET	/bookings/:id	✅	Detalle de reserva
PUT	/bookings/:id	✅	Actualizar reserva
DELETE	/bookings/:id	✅	Cancelar reserva
PUT	/bookings/:id/confirm	🔐	Confirmar reserva (admin)

Ejemplo: Crear Reserva

POST /api/v1/bookings
Authorization: Bearer <token>
Content-Type: application/json

{
  "courtId": "uuid-cancha",
  "date": "2026-02-15",
  "startTime": "18:00",
  "endTime": "19:30",
  "notes": "Con amigos"
}

Estados de Reserva

• PENDING - Pendiente
• CONFIRMED - Confirmada
• CANCELLED - Cancelada
• COMPLETED - Completada
• NO_SHOW - No asistió

---

Módulo: Partidos

Base path: /matches

Método	Endpoint	Auth	Descripción
POST	/matches	✅	Registrar partido
GET	/matches/my-matches	✅	Mis partidos
GET	/matches/history	✅	Historial de partidos
GET	/matches/:id	✅	Detalle de partido
PUT	/matches/:id/confirm	✅	Confirmar partido

Ejemplo: Registrar Partido

POST /api/v1/matches
Authorization: Bearer <token>
Content-Type: application/json

{
  "bookingId": "uuid-reserva",
  "team1Player1Id": "uuid-jugador1",
  "team1Player2Id": "uuid-jugador2",
  "team2Player1Id": "uuid-jugador3",
  "team2Player2Id": "uuid-jugador4",
  "team1Score": 6,
  "team2Score": 4,
  "winner": "TEAM1",
  "playedAt": "2026-02-15T18:00:00Z"
}

---

Módulo: Torneos

Base path: /tournaments

Método	Endpoint	Auth	Descripción
GET	/tournaments	❌	Listar torneos
GET	/tournaments/:id	❌	Detalle de torneo
GET	/tournaments/:id/participants	❌	Participantes
POST	/tournaments	🔐	Crear torneo
PUT	/tournaments/:id	🔐	Actualizar torneo
DELETE	/tournaments/:id	🔐	Eliminar torneo
POST	/tournaments/:id/register	✅	Inscribirse
DELETE	/tournaments/:id/register	✅	Cancelar inscripción
POST	/tournaments/:id/open	🔐	Abrir inscripciones
POST	/tournaments/:id/close	🔐	Cerrar inscripciones
PUT	/tournaments/participants/:id/pay	🔐	Confirmar pago

Ejemplo: Crear Torneo

POST /api/v1/tournaments
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Torneo de Verano 2026",
  "description": "Torneo categoría intermedia",
  "type": "ELIMINATION",
  "category": "MIXED",
  "startDate": "2026-03-01",
  "endDate": "2026-03-15",
  "registrationDeadline": "2026-02-25",
  "maxParticipants": 32,
  "registrationFee": 50000
}

Tipos de Torneo

• ELIMINATION - Eliminación simple
• ROUND_ROBIN - Todos contra todos
• SWISS - Sistema suizo
• CONSOLATION - Consolación

---

Módulo: Ligas

Base path: /leagues

Método	Endpoint	Auth	Descripción
GET	/leagues	✅	Listar ligas
GET	/leagues/my-leagues	✅	Mis ligas
GET	/leagues/:id	✅	Detalle de liga
POST	/leagues	✅	Crear liga
PUT	/leagues/:id	✅	Actualizar liga
DELETE	/leagues/:id	✅	Eliminar liga
POST	/leagues/:id/start	✅	Iniciar liga
POST	/leagues/:id/finish	✅	Finalizar liga
POST	/leagues/:id/cancel	✅	Cancelar liga

Equipos de Liga

Base path: /league-teams

Método	Endpoint	Auth	Descripción
GET	/league-teams	✅	Listar equipos
POST	/league-teams	✅	Crear equipo
PUT	/league-teams/:id	✅	Actualizar equipo
DELETE	/league-teams/:id	✅	Eliminar equipo
POST	/league-teams/:id/members	✅	Agregar miembro
DELETE	/league-teams/:id/members/:userId	✅	Eliminar miembro

---

Módulo: Rankings

Base path: /ranking

Método	Endpoint	Auth	Descripción
GET	/ranking	✅	Ver ranking
GET	/ranking/me	✅	Mi posición
GET	/ranking/top	✅	Top jugadores
PUT	/ranking/users/:id/points	🔐	Actualizar puntos
POST	/ranking/recalculate	🔐	Recalcular rankings

Parámetros de Query

GET /ranking?period=MONTH&periodValue=2026-01&level=INTERMEDIATE&limit=50

Parámetro	Valores	Descripción
period	MONTH, YEAR, ALL_TIME	Período del ranking
periodValue	YYYY-MM o YYYY	Valor del período
level	Todos los niveles	Filtrar por nivel
limit	número	Cantidad de resultados

---

Módulo: Pagos

Base path: /payments

Método	Endpoint	Auth	Descripción
POST	/payments/preference	✅	Crear preferencia de pago
GET	/payments/my-payments	✅	Mis pagos
GET	/payments/:id	✅	Detalle de pago
GET	/payments/:id/status	✅	Estado de pago
POST	/payments/webhook	❌	Webhook MercadoPago
POST	/payments/:id/refund	🔐	Reembolsar pago
POST	/payments/:id/cancel	✅	Cancelar pago

Ejemplo: Crear Preferencia

POST /api/v1/payments/preference
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "BOOKING",
  "referenceId": "uuid-reserva",
  "description": "Reserva Cancha 1 - 15/02/2026 18:00",
  "amount": 22500
}

---

Módulo: Suscripciones

Planes de Suscripción

Base path: /subscription-plans

Método	Endpoint	Auth	Descripción
GET	/subscription-plans	❌	Listar planes activos
GET	/subscription-plans/:id	❌	Detalle de plan
POST	/subscription-plans	🔐	Crear plan
PUT	/subscription-plans/:id	🔐	Actualizar plan
DELETE	/subscription-plans/:id	🔐	Eliminar plan
POST	/subscription-plans/:id/sync-mp	🔐	Sincronizar con MP

Suscripciones de Usuario

Base path: /subscriptions

Método	Endpoint	Auth	Descripción
POST	/subscriptions	✅	Crear suscripción
GET	/subscriptions/my-subscription	✅	Mi suscripción
GET	/subscriptions/benefits	✅	Mis beneficios
GET	/subscriptions/:id	✅	Detalle de suscripción
PUT	/subscriptions/:id/cancel	✅	Cancelar suscripción
PUT	/subscriptions/:id/pause	✅	Pausar suscripción
PUT	/subscriptions/:id/resume	✅	Reanudar suscripción
PUT	/subscriptions/payment-method	✅	Actualizar método de pago
POST	/subscriptions/webhook	❌	Webhook MP

Tipos de Plan

• MONTHLY - Mensual
• QUARTERLY - Trimestral
• YEARLY - Anual

---

Módulo: Amigos

Base path: /friends

Método	Endpoint	Auth	Descripción
GET	/friends	✅	Mis amigos
GET	/friends/pending	✅	Solicitudes pendientes
GET	/friends/sent	✅	Solicitudes enviadas
POST	/friends/request	✅	Enviar solicitud
PUT	/friends/:id/accept	✅	Aceptar solicitud
PUT	/friends/:id/reject	✅	Rechazar solicitud
DELETE	/friends/:id	✅	Eliminar amigo

---

Módulo: Notificaciones

Base path: /notifications

Método	Endpoint	Auth	Descripción
GET	/notifications	✅	Mis notificaciones
GET	/notifications/unread-count	✅	Contador no leídas
PUT	/notifications/:id/read	✅	Marcar como leída
PUT	/notifications/read-all	✅	Marcar todas leídas
DELETE	/notifications/:id	✅	Eliminar notificación
POST	/notifications/bulk	🔐	Notificación masiva
POST	/notifications/cleanup	🔐	Limpiar antiguas

---

Módulo: Wall of Fame

Base path: /wall-of-fame

Método	Endpoint	Auth	Descripción
GET	/wall-of-fame	❌	Listar entradas
GET	/wall-of-fame/featured	❌	Entradas destacadas
GET	/wall-of-fame/search	❌	Buscar entradas
GET	/wall-of-fame/:id	❌	Detalle de entrada
POST	/wall-of-fame	🔐	Crear entrada
PUT	/wall-of-fame/:id	🔐	Actualizar entrada
DELETE	/wall-of-fame/:id	🔐	Eliminar entrada
POST	/wall-of-fame/:id/winners	🔐	Agregar ganadores

---

Módulo: Logros

Base path: /achievements

Método	Endpoint	Auth	Descripción
GET	/achievements	✅	Listar logros
GET	/achievements/my	✅	Mis logros
GET	/achievements/:id	✅	Detalle de logro
GET	/achievements/progress	✅	Mi progreso

---

Módulo: Analytics

Base path: /analytics

Dashboard

Método	Endpoint	Auth	Descripción
GET	/analytics/dashboard/summary	🔐	Resumen dashboard
GET	/analytics/dashboard/today	🔐	Vista de hoy
GET	/analytics/dashboard/calendar	🔐	Calendario semanal

Ocupación

Método	Endpoint	Auth	Descripción
GET	/analytics/occupancy	🔐	Reporte de ocupación
GET	/analytics/occupancy/by-court	🔐	Por cancha
GET	/analytics/occupancy/by-timeslot	🔐	Por franja horaria
GET	/analytics/occupancy/peak-hours	🔐	Horas pico
GET	/analytics/occupancy/comparison	🔐	Comparativa

Finanzas

Método	Endpoint	Auth	Descripción
GET	/analytics/revenue	🔐	Ingresos por período
GET	/analytics/revenue/by-court	🔐	Por cancha
GET	/analytics/revenue/by-type	🔐	Por tipo
GET	/analytics/payment-methods	🔐	Métodos de pago
GET	/analytics/outstanding-payments	🔐	Pagos pendientes
GET	/analytics/refunds	🔐	Reembolsos
GET	/analytics/trends	🔐	Tendencias
GET	/analytics/top-days	🔐	Días top

Reportes

Método	Endpoint	Auth	Descripción
GET	/analytics/reports/revenue	🔐	Reporte ingresos
GET	/analytics/reports/occupancy	🔐	Reporte ocupación
GET	/analytics/reports/users	🔐	Reporte usuarios
GET	/analytics/reports/summary	🔐	Resumen ejecutivo

---

Webhooks

MercadoPago - Pagos

POST /api/v1/payments/webhook

Headers requeridos:

• x-signature - Firma del webhook (opcional si MERCADOPAGO_WEBHOOK_SECRET está configurado)

Eventos procesados:

• payment.created - Pago creado
• payment.updated - Pago actualizado
• merchant_order - Orden de merchant actualizada

MercadoPago - Suscripciones

POST /api/v1/subscriptions/webhook

Eventos procesados:

• subscription_authorized - Suscripción autorizada
• subscription_updated - Suscripción actualizada
• subscription_cancelled - Suscripción cancelada

---

Rate Limiting

La API tiene rate limiting configurado:

• Ventana: 15 minutos (900000ms)
• Máximo de requests: 100 por IP

---

Contacto y Soporte

• Email: soporte@tudominio.com
• Documentación: https://docs.tudominio.com
• Status Page: https://status.tudominio.com

---

Última actualización: Enero 2026