Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven bajo el prefijo /api. En local, la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que el panel lee de NEXT_PUBLIC_API_BASE_URL (Variables de entorno).

Los miembros y el personal usan el mismo inicio de sesión y el mismo token; los roles de la cuenta deciden qué rutas responden. Los cuerpos de las peticiones son JSON, salvo las subidas de archivos. Cada respuesta llega en el mismo envoltorio:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es una frase corta que rellenan algunas escrituras, traducida al idioma de la solicitud, y vacía en los demás casos.

La comprobación de salud es la única ruta fuera del envoltorio. No necesita token y no tiene límite de peticiones:

curl http://localhost:8000/api/health

{"status":"ok"}

Responde 503 con {"status":"unavailable"} mientras no se puede acceder a la base de datos o no tiene tablas, así que una plataforma puede usarla como sonda de disponibilidad.

Errores

Una solicitud fallida responde con el estado HTTP correspondiente y el mismo envoltorio, con success: false, data: null y, en la validación, los problemas por campo:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

Muchos errores llevan en message una clave que traduce el panel, como member_not_found o event_full.

Paginación

Las listas reciben page, desde 1, y page_count, el tamaño de página. Una página contiene como máximo 100 filas: un tamaño mayor se lee como 100, uno menor como 1, y uno ausente o ilegible recurre al valor por defecto de la lista. Una lista responde siempre con la misma forma:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

Las listas de contenido se ordenan por updated_at, de la más reciente a la más antigua por defecto (order=asc o desc), con el id para desempatar, y aceptan search y sus propios filtros.

Idioma

Envía el idioma del lector en la cabecera Accept-Language: en o ar tal como vienen. ar-SA cuenta como árabe, y cualquier idioma que la API no tenga se responde en inglés. Los mensajes de error y el message de una escritura correcta se traducen; el contenido guardado en los dos idiomas vuelve como { "en": "...", "ar": "..." }.

Autenticación

• Inicia sesión en POST /api/auth/login. La respuesta contiene access_token, un JWT firmado con JWT_SECRET, y la cuenta con sus roles y permisos. Envíalo como Authorization: Bearer <token>.
• Un token dura JWT_EXPIRATION, 7d por defecto. No hay ruta de renovación: cuando un token caduca, la siguiente petición responde 401 y el cliente vuelve a iniciar sesión.
• El inicio de sesión, el registro y la eliminación de cuenta aceptan 10 intentos por minuto desde una dirección, contados por ruta, y después responden 429. El recuento se guarda en la memoria de la API, así que empieza de nuevo al reiniciar. Detrás de un proxy, consulta TRUST_PROXY (Solución de problemas).

1. 01

   Inicia sesión como el Head Coach de los datos de demostración

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"headcoach@example.com","password":"Coach@123"}'

   RespuestaCopiar

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "account": { "email": "headcoach@example.com", "roles": [ ], "permissions": [ ] }
     },
     "message": "..."
   }
2. 02

   Llama a una ruta protegida con el token

   TerminalCopiar

   curl "http://localhost:8000/api/users?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Resultado esperado: Los cinco primeros miembros, con la forma de la lista.

No hay ninguna ruta para restablecer la contraseña. Las páginas de contraseña olvidada y de restablecer contraseña del panel son solo las pantallas: no se envía ningún restablecimiento. Una cuenta de personal con members.update establece la contraseña de un miembro con PATCH /api/users/:username/change-password.

Permisos

Una ruta comprueba primero el token y luego el permiso que indica. Una cuenta tiene todos los permisos de todos sus roles; cuando una ruta indica varios, basta con uno cualquiera. En las tablas de abajo, un nombre de permiso en Quién puede llamarla significa una cuenta cuyos roles lo conceden.

• Los roles y sus permisos

Miembros

Coaches y roles

Ajustes de la aplicación

Los datos propios de un miembro

Cada ruta de aquí responde para la cuenta del token y para nadie más. Un token del personal responde 403, porque solo el rol Member tiene fitness.view y fitness.edit. Cada escritura responde con toda la página actualizada.

• Progreso y registro
• Dispositivos y claves de ingesta

Entrenamientos, ejercicios y la sesión

Coaching

Las rutas de la lista de clientes responden para el coach que hace la petición: el cliente de otro coach es un 404.

Los catálogos de contenido

Cada catálogo responde a las mismas cinco rutas bajo /api/fitness/manage/<catalogue>, y todas necesitan fitness.manage. Los catálogos son exercises, workouts, programs, dishes, groups, events, challenges, achievements y badges.

Un id desconocido es 404 record_not_found. Los nombres y textos se envían como { "en": "…", "ar": "…" }; las calorías de un plato nunca se envían, se calculan a partir de sus gramos.

Ingesta

La puerta para dispositivos y agregadores. Estas rutas aceptan una clave de ingesta en X-Api-Key, nunca un token bearer, y solo escriben para la cuenta de la clave.

• Dispositivos y claves de ingesta

Búsqueda, subidas, notificaciones y países

Dos namespaces de Socket.IO en el mismo servidor envían actualizaciones en vivo: /notifications entrega cada notificación nueva, y /auth avisa a un panel con la sesión iniciada de que sus permisos han cambiado. Aceptan los orígenes de FRONTEND_URL, o de CORS_ORIGIN cuando no está configurado.

• Cómo ordena la búsqueda sus resultados

Asistente de IA

Servidor MCP

Rutas del modo demostración