Glicko DB

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

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:

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:

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.

^