workspace/projects/gamilit/docs/API.md

API Documentation

Base URL

Production: http://74.208.126.102:3006/api Development: http://localhost:3006/api

API Documentation (Swagger)

Interactive Docs: http://74.208.126.102:3006/api/docs

Authentication

Todos los endpoints protegidos requieren un token JWT en el header:

Authorization: Bearer <jwt_token>

El token se obtiene al hacer login y tiene una duración de 24 horas.

Core Endpoints

Authentication (/api/auth)

Method	Endpoint	Description	Auth Required
POST	/register	Registrar nuevo usuario	No
POST	/login	Iniciar sesión	No
POST	/logout	Cerrar sesión	Yes
POST	/refresh	Refrescar token	Yes
GET	/profile	Obtener perfil del usuario	Yes
PUT	/profile	Actualizar perfil	Yes
POST	/verify-email	Verificar email	No
POST	/forgot-password	Solicitar reset de contraseña	No
POST	/reset-password	Resetear contraseña con token	No
PUT	/password	Cambiar contraseña	Yes
GET	/sessions	Listar sesiones activas	Yes
DELETE	/sessions/:sessionId	Cerrar sesión específica	Yes
DELETE	/sessions	Cerrar todas las sesiones	Yes

Register User

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

{
  "email": "student@example.com",
  "password": "SecurePass123!",
  "firstName": "Juan",
  "lastName": "Pérez",
  "role": "student"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "student@example.com",
    "firstName": "Juan",
    "lastName": "Pérez",
    "role": "student"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Login

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

{
  "email": "student@example.com",
  "password": "SecurePass123!"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "student@example.com",
    "firstName": "Juan",
    "role": "student"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "24h"
}

Users (/api/users)

Method	Endpoint	Description	Auth Required
GET	/profile	Obtener perfil actual	Yes
PUT	/profile	Actualizar perfil	Yes
GET	/preferences	Obtener preferencias	Yes
PUT	/preferences	Actualizar preferencias	Yes
POST	/avatar	Subir avatar	Yes
GET	/statistics	Estadísticas del usuario	Yes

Password Management (/api/password)

Method	Endpoint	Description	Auth Required
POST	/reset-password/request	Solicitar reset	No
POST	/reset-password	Resetear con token	No
PUT	/change-password	Cambiar contraseña	Yes
POST	/verify-email	Verificar email	No
POST	/verify-email/resend	Reenviar verificación	Yes
GET	/verify-email/status	Estado de verificación	Yes

Gamification Endpoints

Ranks (/api/gamification/ranks)

Maya ranking system con 5 niveles.

Method	Endpoint	Description	Auth Required
GET	/	Listar todos los rangos	Yes
GET	/current	Obtener rango actual del usuario	Yes
GET	/:id	Obtener detalles de un rango	Yes
GET	/users/:userId/rank-progress	Progreso hacia siguiente rango	Yes
GET	/users/:userId/rank-history	Historial de rangos	Yes
GET	/check-promotion/:userId	Verificar si califica para promoción	Yes
POST	/promote/:userId	Promover a siguiente rango	Yes (Admin)
POST	/admin/ranks	Crear nuevo rango	Yes (Admin)
PUT	/admin/ranks/:id	Actualizar rango	Yes (Admin)
DELETE	/admin/ranks/:id	Eliminar rango	Yes (Admin)

Maya Ranks:

1. MERCENARIO (0-1000 pts)
2. GUERRERO (1000-2500 pts)
3. HOLCATTE (2500-5000 pts)
4. BATAB (5000-10000 pts)
5. NACOM (10000+ pts)

Get Current Rank

GET /api/gamification/ranks/current
Authorization: Bearer <token>

Response:

{
  "rank": {
    "id": "uuid",
    "name": "GUERRERO",
    "level": 2,
    "minPoints": 1000,
    "maxPoints": 2500,
    "multiplier": 1.2,
    "icon": "⚔️"
  },
  "currentPoints": 1500,
  "progress": 0.2,
  "nextRank": {
    "name": "HOLCATTE",
    "pointsNeeded": 1000
  }
}

Achievements (/api/gamification/achievements)

Method	Endpoint	Description	Auth Required
GET	/achievements	Listar logros disponibles	Yes
GET	/achievements/:id	Detalles de un logro	Yes
GET	/users/:userId/achievements	Logros del usuario	Yes
POST	/users/:userId/achievements/:achievementId	Otorgar logro	Yes (System)
GET	/users/:userId/achievements/summary	Resumen de logros	Yes
POST	/users/:userId/achievements/:achievementId/claim	Reclamar recompensa	Yes
PATCH	/achievements/:id	Actualizar logro	Yes (Admin)

Leaderboard (/api/gamification/leaderboard)

Method	Endpoint	Description	Auth Required
GET	/leaderboard/global	Leaderboard global	Yes
GET	/leaderboard/schools/:schoolId	Leaderboard por escuela	Yes
GET	/leaderboard/classrooms/:classroomId	Leaderboard por clase	Yes
GET	/leaderboard/friends/:userId	Leaderboard de amigos	Yes

Get Global Leaderboard

GET /api/gamification/leaderboard/global?limit=10&period=week
Authorization: Bearer <token>

Response:

{
  "leaderboard": [
    {
      "rank": 1,
      "userId": "uuid",
      "name": "Juan Pérez",
      "points": 5000,
      "rank": "HOLCATTE",
      "avatar": "url"
    },
    ...
  ],
  "userPosition": {
    "rank": 15,
    "points": 2000
  }
}

Missions (/api/gamification/missions)

Method	Endpoint	Description	Auth Required
GET	/daily	Misiones diarias	Yes
GET	/weekly	Misiones semanales	Yes
GET	/special	Misiones especiales	Yes
GET	/stats/:userId	Estadísticas de misiones	Yes
POST	/:id/start	Iniciar misión	Yes
PATCH	/:id/progress	Actualizar progreso	Yes
POST	/:id/claim	Reclamar recompensa	Yes

Shop (/api/gamification/shop)

Method	Endpoint	Description	Auth Required
GET	/categories	Categorías de items	Yes
GET	/items	Listar items disponibles	Yes
GET	/items/:id	Detalles de un item	Yes
POST	/purchase	Comprar item	Yes
GET	/purchases/:userId	Historial de compras	Yes
GET	/owned/:userId/:itemId	Verificar si posee item	Yes

ML Coins (/api/gamification/ml-coins)

Moneda virtual del sistema.

Method	Endpoint	Description	Auth Required
GET	/users/:userId/ml-coins	Balance de ML Coins	Yes
GET	/users/:userId/ml-coins/transactions	Historial de transacciones	Yes
POST	/users/:userId/ml-coins/add	Agregar ML Coins	Yes (System)
POST	/users/:userId/ml-coins/spend	Gastar ML Coins	Yes

User Stats (/api/gamification/user-stats)

Method	Endpoint	Description	Auth Required
GET	/users/:userId/stats	Estadísticas completas	Yes
GET	/users/:userId/summary	Resumen de estadísticas	Yes
GET	/users/:userId/rank	Información de rango	Yes
PATCH	/users/:userId/stats	Actualizar estadísticas	Yes (System)

Educational Endpoints

Content (/api/content)

Gestión de contenido educativo.

Method	Endpoint	Description	Auth Required	Roles
GET	/subjects	Listar materias	Yes	All
GET	/subjects/:id	Detalles de materia	Yes	All
GET	/subjects/:id/modules	Módulos de una materia	Yes	All
GET	/modules/:id/lessons	Lecciones de un módulo	Yes	All
GET	/lessons/:id	Detalles de una lección	Yes	All
POST	/subjects	Crear materia	Yes	Teacher, Admin
PUT	/subjects/:id	Actualizar materia	Yes	Teacher, Admin
DELETE	/subjects/:id	Eliminar materia	Yes	Admin

Assignments (/api/assignments)

Gestión de tareas y quizzes.

Method	Endpoint	Description	Auth Required	Roles
GET	/	Listar assignments	Yes	All
GET	/:id	Detalles de assignment	Yes	All
POST	/	Crear assignment	Yes	Teacher
PUT	/:id	Actualizar assignment	Yes	Teacher
DELETE	/:id	Eliminar assignment	Yes	Teacher
POST	/:id/submit	Enviar respuestas	Yes	Student
GET	/:id/submissions	Ver envíos	Yes	Teacher
POST	/:id/grade	Calificar envío	Yes	Teacher

Submit Assignment

POST /api/assignments/:id/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "answers": [
    {
      "questionId": "uuid",
      "answer": "La respuesta correcta"
    },
    ...
  ]
}

Response:

{
  "submission": {
    "id": "uuid",
    "score": 85,
    "pointsAwarded": 850,
    "feedback": "¡Buen trabajo!",
    "correctAnswers": 17,
    "totalQuestions": 20
  },
  "gamification": {
    "pointsEarned": 850,
    "rankMultiplier": 1.2,
    "streakMultiplier": 1.1,
    "currentRank": "GUERRERO",
    "newAchievements": ["first_quiz_completed"]
  }
}

Progress (/api/progress)

Tracking de progreso estudiantil.

Method	Endpoint	Description	Auth Required
GET	/users/:userId	Progreso general del usuario	Yes
GET	/users/:userId/subjects/:subjectId	Progreso en una materia	Yes
GET	/users/:userId/modules/:moduleId	Progreso en un módulo	Yes
GET	/analytics	Analytics agregados	Yes (Teacher)

Admin Endpoints

Admin Dashboard (/api/admin/dashboard)

Method	Endpoint	Description	Auth Required
GET	/stats	Estadísticas generales	Yes (Admin)
GET	/activity	Actividad reciente	Yes (Admin)
GET	/alerts	Alertas del sistema	Yes (Admin)

Admin Users (/api/admin/users)

Method	Endpoint	Description	Auth Required
GET	/	Listar usuarios	Yes (Admin)
GET	/:id	Detalles de usuario	Yes (Admin)
POST	/	Crear usuario	Yes (Admin)
PUT	/:id	Actualizar usuario	Yes (Admin)
DELETE	/:id	Eliminar usuario	Yes (Admin)
POST	/:id/ban	Banear usuario	Yes (Admin)
POST	/:id/unban	Desbanear usuario	Yes (Admin)

Admin Reports (/api/admin/reports)

Method	Endpoint	Description	Auth Required
GET	/usage	Reporte de uso	Yes (Admin)
GET	/performance	Reporte de rendimiento	Yes (Admin)
GET	/gamification	Reporte de gamificación	Yes (Admin)
POST	/export	Exportar reportes	Yes (Admin)

Notifications

Push Notifications (/api/notifications)

Method	Endpoint	Description	Auth Required
GET	/	Listar notificaciones	Yes
GET	/:id	Detalles de notificación	Yes
PATCH	/:id/read	Marcar como leída	Yes
PATCH	/mark-all-read	Marcar todas como leídas	Yes
DELETE	/:id	Eliminar notificación	Yes
POST	/subscribe	Suscribirse a push	Yes
DELETE	/unsubscribe	Desuscribirse de push	Yes

WebSocket Events

Connection: ws://74.208.126.102:3006

Events emitted by server:

• notification - Nueva notificación
• points_awarded - Puntos otorgados
• rank_upgraded - Promoción de rango
• achievement_unlocked - Logro desbloqueado
• assignment_graded - Tarea calificada
• new_message - Nuevo mensaje

Events to emit:

• join_room - Unirse a sala
• leave_room - Salir de sala
• typing - Usuario escribiendo

Health & Monitoring

Health Check (/api/health)

Method	Endpoint	Description	Auth Required
GET	/	Health check general	No
GET	/db	Database health	No
GET	/redis	Redis health	No

Response:

{
  "status": "ok",
  "timestamp": "2025-12-12T10:00:00Z",
  "uptime": 3600,
  "services": {
    "database": "healthy",
    "redis": "healthy"
  }
}

Error Responses

Todos los endpoints pueden retornar errores en el siguiente formato:

{
  "statusCode": 400,
  "message": "Descripción del error",
  "error": "Bad Request",
  "timestamp": "2025-12-12T10:00:00Z",
  "path": "/api/endpoint"
}

Common Error Codes

Code	Description
400	Bad Request - Datos inválidos
401	Unauthorized - Token inválido o expirado
403	Forbidden - Sin permisos
404	Not Found - Recurso no encontrado
409	Conflict - Conflicto (ej: email ya existe)
422	Unprocessable Entity - Validación fallida
429	Too Many Requests - Rate limit excedido
500	Internal Server Error - Error del servidor

Rate Limiting

• General: 100 requests por minuto por IP
• Auth endpoints: 5 requests por minuto
• File uploads: 10 requests por hora

Pagination

Endpoints que retornan listas soportan paginación:

GET /api/endpoint?page=1&limit=20&sortBy=createdAt&order=DESC

Response:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}

Filtering & Search

Muchos endpoints soportan filtrado:

GET /api/users?role=student&status=active&search=juan

CORS

CORS está habilitado para los siguientes orígenes:

• http://localhost:3005 (development)
• http://74.208.126.102:3005 (production)

API Versioning

Actualmente en versión 1. Las rutas futuras incluirán versionado:

• /api/v1/endpoint (futuro)
• /api/endpoint (actual, equivalente a v1)

SDK Usage (Future)

import { GamilitClient } from '@gamilit/sdk';

const client = new GamilitClient({
  baseUrl: 'http://74.208.126.102:3006/api',
  token: 'your-jwt-token'
});

// Login
await client.auth.login({ email, password });

// Get current rank
const rank = await client.gamification.getCurrentRank();

// Submit assignment
const result = await client.assignments.submit(assignmentId, answers);

Additional Resources

• Swagger UI: http://74.208.126.102:3006/api/docs
• Architecture: ARCHITECTURE.md
• Deployment: DEPLOYMENT.md
• Database Schema: /apps/database/ddl/