Referencia API de torneos - Exura Tech · Integración para brokers

Base: origen de la API, por ejemplo https://api.example.com. La instancia publica OpenAPI en /docs y /openapi.json. Las fechas de creación/edición deben llevar zona horaria; los valores se normalizan a UTC. Los IDs numéricos y UUID cumplen funciones distintas: administración y credenciales suelen usar id; enlaces públicos usan uuid.

Administración

Método	Ruta	Permiso	Uso
`POST`	`/api/v1/tournaments`	Admin	Crea torneo, premios y opcionalmente ventana de registro; `201`
`PATCH`	`/api/v1/tournaments/{id}`	Admin	Cambia campos y reemplaza premios si se envían
`DELETE`	`/api/v1/tournaments/{id}`	Admin	Borra solo si no hay cuentas MT5 asociadas
`POST` / `PUT`	`/api/v1/tournaments/{uuid}/registration-dates`	Admin	Crea / actualiza ventana de inscripción
`GET`	`/api/v1/tournaments/{id}/registrations`	Admin	Inscritos y cuentas; contiene datos personales y credenciales
`POST`	`/api/v1/tournaments/by-uuid/{uuid}/invite`	Admin	Envía invitación al enlace privado; cuerpo `{"email":"..."}`

POST /api/v1/tournaments recibe company_id, name, slug y campos opcionales ranking_metric, status, initial_balance, currency, mt5_group, leverage, competition_start_at, competition_end_at, max_participants, min_trading_days, porcentajes de drawdown/objetivo, rules_json, registration_start_at, registration_end_at, prizes. El ejemplo completo está en Configuración. Los premios incorporados usan rank_from, rank_to, prize_type, amount, currency, description y no requieren llamada separada. GET /api/v1/tournament-prizes?tournament_id={id} requiere bearer y permite consultarlos; el detalle público de torneo ya incluye prizes.

Usuario e inscripción

Método	Ruta	Permiso	Cuerpo / respuesta
`POST`	`/api/v1/users`	Público	`email`, `password`, `first_name`, `last_name`; crea usuario inactivo y envía código
`POST`	`/api/v1/users/verify-code`	Público	`email`, `code`; activa usuario
`POST`	`/auth/login`	Público	`email`, `password`; devuelve JWT de usuario
`POST`	`/auth/forgot-password`	Público	`email`; solicita enlace
`POST`	`/auth/reset-password`	Público	`email`, `code`, `new_password`
`GET`	`/api/v1/users/me`	JWT usuario	Perfil propio
`POST`	`/api/v1/registrations`	JWT usuario	`tournament_id`, `user_id` requerido por esquema, `status` opcional; servidor impone usuario del JWT
`GET`	`/api/v1/registrations/me`	JWT usuario	Inscripciones propias
`GET`	`/api/v1/tournaments/{id}/my-credentials`	JWT usuario	Solo credenciales de su propia cuenta
`POST`	`/api/v1/tournaments/by-uuid/{uuid}/private-enroll`	Público con enlace	`first_name`, `last_name`, `email`, `send_email` opcional; crea usuario/cuenta

POST /api/v1/registrations responde 201 con la inscripción, o 400 si ventana/cupo no permiten alta, 404 si no existe torneo, 409 si ya está inscrito y 500 ante falla de conexión/creación MT5. El enlace privado comparte ventana/cupo y puede devolver 409 para usuario ya inscrito. No equivale al endpoint CRM de competencias.

Lecturas públicas

Método	Ruta	Uso
`GET`	`/api/v1/tournaments?company_id={id}&status={status}`	Lista, filtro de compañía/estado
`GET`	`/api/v1/tournaments/by-uuid/{uuid}`	Detalle, fechas, premios y `can_register`
`GET`	`/api/v1/tournaments/{uuid}/registration-dates`	Fechas registradas; `404` si faltan
`GET`	`/api/v1/tournaments/by-uuid/{uuid}/leaderboard?limit=100&offset=0`	Ranking; `limit` 1–500
`GET`	`/api/v1/tournaments/by-uuid/{uuid}/participant/{login}/live-stats?include_history=true`	Detalle y curvas
`GET`	`/api/v1/tournaments/latest-live`	Último torneo marcado `LIVE`; `404` si no hay

La API también expone variantes por ID de leaderboard y estadísticas bajo /api/v1/tournaments/{id}/... que requieren bearer genérico. Para frontend público usa las rutas por UUID de esta tabla. Un panel propio debe proteger las rutas administrativas con sesión admin y separar los JWT de participantes. Confirma esquemas de la versión desplegada en OpenAPI antes de desarrollar un cliente generado.

Estadísticas por ID y sincronización manual

Método	Ruta	Acceso	Uso
`GET`	`/api/v1/tournaments/{id}/leaderboard`	Bearer	Ranking por ID
`GET`	`/api/v1/tournaments/{id}/average-live-charts`	Bearer	Curvas agregadas; puede leer múltiples historiales MT5
`GET`	`/api/v1/tournaments/{id}/participant/{login}/live-stats`	Bearer	Detalle por ID
`POST`	`/api/v1/mt5-sync/tournaments/{id}`	Bearer	Sincronización manual de un torneo
`POST`	`/api/v1/mt5-sync/live-tournaments`	Bearer	Sincronización manual de torneos en vivo

Estas rutas no reemplazan los workers programados. Evita llamarlas desde cada navegador o en cada refresco de página: algunas hacen lecturas MT5 costosas. Para un sitio público usa leaderboard y detalle por UUID, con histórico solicitado bajo demanda. Las rutas /api/v1/mt5-accounts gestionan registros locales de cuentas y pueden incluir datos sensibles; tampoco son fuente para una tabla pública.

Formas de respuesta

El detalle público de torneo incluye id, uuid, status, url, public_url, ranking_metric, fechas, registration_window, can_register, registered_users_count y prizes, además de la configuración enviada al crearlo. El leaderboard entrega:

{
  "ranking_metric": "equity",
  "tournament_id": 12,
  "tournament_uuid": "<tournament-uuid>",
  "tournament_name": "Torneo de ejemplo",
  "generated_at": "2026-11-01T12:15:00",
  "total": 1,
  "items": [{
    "rank": 1,
    "mt5_account_id": 98,
    "user_id": 34,
    "user_email": "ana@example.com",
    "first_name": "Ana",
    "last_name": "Pérez",
    "login": 12345678,
    "initial_balance": "50000.00",
    "current_balance": "50100.00",
    "current_equity": "50120.00",
    "current_profit": "100.00",
    "win_rate": null,
    "profit_factor": null,
    "roi": null,
    "total_trades": 0,
    "trades": 0,
    "positions": 0,
    "status": "ACTIVE",
    "last_sync_at": "2026-11-01T12:14:50"
  }]
}

El ejemplo ilustra el esquema; fechas y valores pueden ser null hasta sincronizar y el serializador de una versión concreta puede variar el formato UTC. live-stats devuelve active_positions, total_trades, last_trades, chart_data, account_growth_chart, performance_curve_chart, win_rate, profit_factor, roi y current_profit. Las curvas son listas de puntos {time, value}. Verifica la respuesta real de tu entorno en OpenAPI.

​Administración

​Usuario e inscripción

​Lecturas públicas

​Estadísticas por ID y sincronización manual

​Formas de respuesta

Administración

Usuario e inscripción

Lecturas públicas

Estadísticas por ID y sincronización manual

Formas de respuesta