Rutas y notas de integración
Consulta la Ayuda de la interfaz para instrucciones orientadas a tareas y el README en español para instalación y configuración.
Tabla de contenidos
- Estado de la API
- Rutas GET públicas
- Visibilidad y ratings de torneos
- Autenticación y rutas de miembros
- Grupos de rutas administrativas
- Recomendaciones para integraciones
Estado de la API
Los resultados de idempotencia completados se conservan al menos 90 días. Los nuevos usan UTC para su retención; los anteriores con zona horaria desconocida se conservan indefinidamente para evitar su caducidad prematura.
El campo reviewed_at de un envío es null cuando no se ha revisado o cuando se desconoce la zona horaria de una revisión anterior; las nuevas revisiones web y API ofrecen una marca de tiempo UTC.
La aplicación sigue renderizada en el servidor y dispone de una API autenticada en /api/v1. Las operaciones v1 son GET /me; lecturas de jugadores, rankings, partidas, torneos, participantes, rondas, emparejamientos, clasificaciones e informes; envíos de resultados de miembros; moderación administrativa; y comandos de torneos. GET /api/v1/openapi.json contiene el contrato completo. Cada solicitud API requiere un token bearer con el alcance de la operación y el permiso vigente del rol de la cuenta. Crea y administra tokens personales desde el perfil: los administradores eligen los alcances del token y las demás cuentas reciben los que permiten sus roles actuales. Las antiguas rutas /api/backup, /api/player y /api/tournament no existen.
Las operaciones se agrupan en bloques de despliegue que los operadores habilitan por separado con API_ENABLED_SLICES; todos están deshabilitados por defecto. Los bloques son docs (OpenAPI), reads, submissions, moderation, tournament_setup (crear/configurar), tournament_participants y tournament_rounds (rondas, resultados y procesamiento). El documento OpenAPI indica el bloque de cada operación en x-rollout-slice. Un bloque deshabilitado responde 503 con el código api_slice_disabled; un bloque incluido en API_STAFF_PILOT_SLICES responde 503 con api_pilot_restricted a las cuentas que no son del personal. La configuración, el orden de despliegue y la reversión están en el README.
Los envíos de resultados requieren Idempotency-Key; las decisiones de moderación y los comandos condicionales usan If-Match con el ETag actual. Los comandos de torneos requieren el alcance, permiso y ámbito geográfico correspondientes. PairGo es siempre no puntuable y sus partidas aparecen como emparejamientos, no en las rutas de partidas individuales. Consulta el contrato v1 para los requisitos, límites y efectos de cada operación.
Las acciones administrativas son envíos de formularios HTML. Requieren una sesión autenticada, el rol correspondiente y un token CSRF válido. Algunas acciones administrativas asíncronas devuelven una pequeña respuesta JSON de redirección solo cuando la solicitud incluye X-Requested-With: XMLHttpRequest; esto es un comportamiento interno del navegador, no un contrato de API versionado.
Rutas GET públicas
Estas páginas se pueden abrir sin una cuenta de administrador:
| Ruta | Uso |
|---|---|
/ |
Inicio, resumen de posiciones, estadísticas y noticias publicadas |
/rankings |
Posiciones públicas paginadas |
/players |
Directorio y filtros de jugadores |
/player/view?id=<player_id> |
Perfil e historial de partidas de un jugador |
/matches |
Lista y filtros de partidas |
/tournaments |
Lista de torneos públicos |
/tournaments/<tournament_id> |
Detalles, emparejamientos y clasificación de un torneo |
/tournaments/<tournament_id>/matches/<pairing_id> |
Detalle de una partida PairGo pública |
/reports |
Reportes por periodo y jugador |
/reports/export.csv |
Versión CSV de los filtros del reporte |
/reports/export.pdf |
Versión PDF de los filtros del reporte |
/category |
Información de rating Glicko y categorías |
/sgf-library |
Biblioteca pública de SGF |
/sgf-library/<filename> |
Metadatos de un registro SGF |
/sgf/<filename> |
Descarga de un registro SGF |
/matches/<match_id>/record |
Visualización del SGF vinculado a una partida |
/matches/<match_id>/sgf |
Descarga del SGF vinculado a una partida |
/news/<article_id> |
Artículo de noticias publicado |
La mayoría de las páginas acepta el parámetro opcional lang=es, lang=en o lang=pt. /rankings acepta country (ISO 3166-1 alpha-3; también reconoce códigos alpha-2 heredados), region=latam y group=u18|women. Si se omite region, se usa la región configurada por el administrador, inicialmente América Latina; region=all o region= incluye todas las regiones. Los filtros se intersectan: un país fuera de América Latina requiere seleccionar todas las regiones cuando ese es el valor predeterminado. GET /api/v1/rankings usa la misma región predeterminada y permite las mismas opciones de región; sus filtros group repetidos usan OR, mientras que en la web se intersectan. El grupo u18 también incluye jugadores sub-18 con año de nacimiento desconocido. Los reportes también aceptan start_date, end_date y player_id; consulta la guía de interfaz para más detalles.
Visibilidad y ratings de torneos
El campo API last_active del jugador es la fecha de su última partida individual pública jugada, o null si no existe una válida. Incluye partidas individuales no puntuables; excluye borradores, canceladas, PairGo, descansos, ausencias y fechas inválidas. GET /api/v1/players?last_active_days=N usa un límite inclusivo desde la fecha actual de la aplicación, y sort=activity usa esa misma fecha. Los filtros de actividad de las clasificaciones web usan la misma elegibilidad. La migración al iniciar completa las fechas existentes; la actualización normal de estadísticas y los cambios de visibilidad las mantienen al día sin cambiar la elegibilidad del rating.
Comportamiento actual:
/tournamentsmuestra torneos activos y completados. Los organizadores, gestores y administradores también pueden incluir borradores conshow_drafts=1; los torneos cancelados no aparecen en la lista.- El detalle individual cancelado sigue accesible por enlace directo en la web y con
tournaments:readen la API autenticada. Las páginas web de detalle de PairGo cancelado siguen reservadas al personal. - Las páginas públicas de partidas y los perfiles ocultan partidas vinculadas a torneos en borrador o cancelados. El historial de torneos de los perfiles de jugadores muestra únicamente torneos completados.
- El recálculo de ratings incluye partidas independientes y partidas vinculadas a torneos completados puntuables. Las partidas de torneos no puntuables, activos, en borrador o cancelados no afectan a los ratings.
- PairGo siempre es no puntuable. Las parejas tienen dos integrantes sin restricciones de género; sus partidas aparecen en la lista web y ambos perfiles, pero no alteran estadísticas individuales ni enfrentamientos directos.
- Cambiar el estado de un torneo que agrega o quita partidas completadas marca la fecha más antigua afectada, sin recalcular los ratings inmediatamente. Usa el recálculo completo o la actualización incremental en
/admin/ratingspara aplicar el cambio.
Estas reglas se aplican a partidas vinculadas mediante el emparejamiento del torneo; las partidas independientes siguen contando para los ratings. Consulta FUTURE_FEATURES.md para las demás propuestas pendientes.
Autenticación y rutas de miembros
| Ruta | Método | Acceso |
|---|---|---|
/admin/login |
GET, POST | Iniciar sesión |
/admin/register |
GET, POST | Crear una cuenta de miembro |
/admin/forgot-password |
GET, POST | Solicitar un enlace de recuperación |
/admin/reset-password/<token> |
GET, POST | Completar la recuperación |
/admin/report-results |
GET, POST | Enviar resultados del jugador vinculado o solicitar vínculo con un jugador sin cuenta |
/admin/profile |
GET, POST | Gestionar el perfil de una cuenta autenticada |
/admin/logout |
GET | Cerrar la sesión actual |
Los envíos de miembros permanecen pendientes hasta su revisión. Antes de ser aprobados no afectan las partidas públicas, los ratings ni los reportes.
Los miembros sin vínculo envían action=request_player_link y player_id mediante el formulario Reportar resultados protegido con CSRF. Las solicitudes comparten la página de moderación y su filtro de estado. POST /admin/player-link-requests/<request_id>/approve y /reject requieren un gestor del país/región del jugador o un administrador global. La aprobación vincula al jugador aún disponible, registra revisión/auditoría e invalida sesiones/tokens del miembro en una transacción. Las aprobaciones repetidas o conflictivas no sobrescriben vínculos. Solo se admite una solicitud pendiente por miembro; el rechazo permite otra solicitud. Son rutas web, no recursos API.
Grupos de rutas administrativas
Todas las rutas siguientes requieren una cuenta autenticada y permisos según el rol:
/admin: panel de administración/admin/analytics:GET /admin/analytics— panel de métricas agregadas del sitio de los últimos 30 días, solo para administradores/admin/import: importaciones de Excel, CSV y OpenGotha/admin/backups: crear, restaurar y eliminar copias administradas/admin/players,/admin/players/import,/admin/matches: gestión de jugadores y partidas, incluida la importación de jugadores desde CSV/XLSX/admin/ratings,/admin/categories: configuración de ratings y categorías/admin/tournaments: creación y gestión de torneos, con copia y eliminación por lotes de hasta 100 torneos seleccionados/admin/tournaments/<tournament_id>/...: participantes, emparejamientos, resultados, rondas y exportación/admin/tournaments/<tournament_id>/participants/add-batchy/admin/tournaments/<tournament_id>/participants/remove-batch: inscribir o retirar hasta 100 participantes seleccionados de forma atómica/admin/sgf/...: vinculación y eliminación de SGF;/admin/sgf/delete-batchelimina hasta 100 archivos seleccionados y limpia las referencias de partidas vinculadas y envíos pendientes/admin/news: gestión de noticias/admin/users,/admin/audit,/admin/settings: cuentas, auditoría y configuración
Los tres niveles del personal son Global, Regional y País. country_organizer y regional_organizer tienen Operaciones de torneos, incluyendo creación de jugadores desde torneos, edición/eliminación, partidas, vinculación SGF y flujos/importación de torneos. country_manager y regional_manager también tienen Gestión de datos: importación de jugadores, noticias y moderación de resultados. Los jugadores y la moderación se filtran geográficamente; una partida requiere al menos un jugador dentro del ámbito y un torneo un país dentro del ámbito. Las noticias son contenido compartido del sitio. Los roles de país requieren un país (con respaldo del jugador vinculado); los regionales requieren una región explícita admitida. Sin ámbito compatible, se deniega el acceso geográfico. Los administradores tienen acceso global.
El menú se organiza por tareas, no por roles: Jugadores y competición, Importaciones y ratings, Contenido y registros de partidas y Administración del sitio. Los permisos no cambian: todas las operaciones de copias, /admin/import, ratings/categorías, usuarios, auditoría, configuración y eliminación de SGF siguen reservadas a administradores. Las cuentas operator y tournament_director migran a regional_manager y regional_organizer, respectivamente, con ámbito de América Latina e invalidación de sesiones/tokens. Las lecturas API conservan la visibilidad pública; las lecturas de torneos en borrador también exigen un permiso vigente del personal y un ámbito geográfico coincidente.
Las rutas POST cambian el estado de la aplicación y deben usarse mediante los formularios renderizados. Las cargas OpenGotha desde /admin/import o /admin/tournaments muestran la misma vista de revisión antes de la aprobación explícita; la vista se vincula al usuario, al archivo y al estado de la base de datos y caduca a los 15 minutos. Las acciones de copias, restauración, importación, eliminación y torneos no están expuestas como operaciones GET sin autenticación. Las acciones por lotes requieren los mismos permisos de rol y protección CSRF que sus equivalentes individuales; las acciones por lotes de participantes de torneos también requieren claves de idempotencia.
Recomendaciones para integraciones
Para una integración externa, usa las operaciones API autenticadas documentadas para las funciones disponibles y las exportaciones CSV/PDF para los demás informes. No dependas de formularios administrativos ni de respuestas JSON no documentadas.
Las etapas A0-A6 están completas; sus procedimientos y observaciones están en las notas operativas. La hoja de ruta contiene solo propuestas y verificaciones pendientes. Consulta GET /api/v1/openapi.json para conocer los parámetros y esquemas.
El contrato OpenAPI 3.1 aprobado y sus decisiones de autenticación, permisos y formato están disponibles en el contrato de API v1 y en el documento OpenAPI legible por máquina. Usa un token personal con el alcance exacto que exige cada operación; envía tokens solo en el encabezado Authorization y mediante HTTPS. Con un prefijo de ruta como /glicko, usa las URL con prefijo que devuelven Location y la entrada servers del documento OpenAPI.
Ejemplo de solicitud (PowerShell; guarda el token en una variable de entorno, nunca en la URL):
$headers = @{ Authorization = "Bearer $env:GLICKO_API_TOKEN" }
Invoke-RestMethod -Uri "https://example.org/api/v1/rankings?per_page=5" -Headers $headers
Para verificar un despliegue, ejecuta el cliente de prueba (solo usa la biblioteca estándar) con un token piloto. Solo envía sondeos sin efectos secundarios, salvo con --write-draft-tournament, que crea un borrador y debe usarse únicamente con datos desechables:
$env:GLICKO_API_TOKEN = "<token piloto>"
python scripts/api_smoke_test.py --base-url https://example.org --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds
Imprime un informe JSON y termina con 0 si todas las comprobaciones pasan, 1 si alguna falla y 2 si el uso es inválido.