# 📚 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](#introducción)
- [Autenticación](#autenticación)
- [Base URL](#base-url)
- [Formatos de Respuesta](#formatos-de-respuesta)
- [Códigos de Error](#códigos-de-error)
- [Módulos](#módulos)
  - [Autenticación](#módulo-autenticación)
  - [Usuarios](#módulo-usuarios)
  - [Canchas](#módulo-canchas)
  - [Reservas](#módulo-reservas)
  - [Partidos](#módulo-partidos)
  - [Torneos](#módulo-torneos)
  - [Ligas](#módulo-ligas)
  - [Rankings](#módulo-rankings)
  - [Pagos](#módulo-pagos)
  - [Suscripciones](#módulo-suscripciones)
  - [Amigos](#módulo-amigos)
  - [Notificaciones](#módulo-notificaciones)
  - [Wall of Fame](#módulo-wall-of-fame)
  - [Logros](#módulo-logros)
  - [Analytics](#módulo-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

```http
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

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

### Niveles de Jugador

```typescript
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

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

### Respuesta de Lista (Paginada)

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

### Respuesta de Error

```json
{
  "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

```json
// 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:**
```http
POST /api/v1/auth/register
Content-Type: application/json

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

**Login:**
```http
POST /api/v1/auth/login
Content-Type: application/json

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

**Respuesta exitosa:**
```json
{
  "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

```http
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

```http
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

```http
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

```http
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

```http
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

```http
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*