API de desarrollador
Documentación de la API de clasificación de ajedrez
La API Chess Rating proporciona acceso programático al mismo motor de cálculo Elo que impulsa las calculadoras de este sitio. Los desarrolladores que crean herramientas de gestión de clubes, paneles de informes de torneos, plataformas de entrenamiento o productos editoriales pueden integrar cálculos de calificación directamente en sus flujos de trabajo sin volver a implementar la lógica de la fórmula. Esta documentación cubre los puntos finales disponibles, los formatos de solicitud y respuesta, los requisitos de autenticación y el enfoque de control de versiones que mantiene estables las integraciones. Puedes continuar con Widgets de clasificación de ajedrez integrables para una guía relacionada.
Puntos finales de cálculo disponibles
La API admite tres flujos de trabajo de cálculo principales: cambio de calificación de un solo juego (dadas dos calificaciones, un resultado y un factor K), procesamiento por lotes (múltiples registros de juego en una solicitud) y estimación de calificación inicial (dada la calificación promedio del oponente, la puntuación y el recuento de juegos). Cada punto final devuelve el mismo resultado detallado que se muestra en las páginas de la calculadora, incluida la puntuación esperada, el delta de calificación y la nueva calificación proyectada. Para detalles de implementación y validación, revisa la metodología.
Los puntos finales del modo torneo aceptan una variedad ordenada de calificaciones y resultados de los oponentes, y devuelven desgloses por ronda y totales acumulativos. Todas las respuestas incluyen metadatos sobre qué perfil de reglas se aplicó para que los consumidores intermedios puedan verificar los supuestos de cálculo.
Límites de autenticación y velocidad
El acceso a la API requiere una clave de API pasada como token de portador en el encabezado de Autorización. Las claves están disponibles en niveles gratuitos y premium. El nivel gratuito permite hasta 100 solicitudes por día con un máximo de 10 juegos por solicitud por lote. Las claves premium desbloquean un mayor rendimiento, soporte prioritario y acceso a puntos finales de procesamiento masivo de torneos.
Los límites de velocidad se aplican por clave, no por dirección IP. Exceder el límite devuelve un estado 429 con un encabezado Retry-After que indica cuándo se abre la siguiente ventana de solicitud. Todos los límites están documentados en los encabezados de respuesta de cada solicitud exitosa.
Perfiles de reglas y control de versiones
Cada respuesta de API incluye un campo reglas_perfil que indica qué conjunto de suposiciones se utilizó para el cálculo (por ejemplo, fide_2024, us_chess_current, generic_elo). Cuando cambian las regulaciones de la federación, la API agrega una nueva versión del perfil en lugar de modificar las existentes. Esto significa que los sistemas posteriores pueden fijar una versión de perfil específica y actualizarla según su propio cronograma.
Los cambios importantes se comunican con al menos 30 días de anticipación a través del registro de cambios de API y la lista de correo de desarrolladores. Las adiciones continuas (nuevos campos opcionales, nuevos perfiles) se implementan continuamente sin interrumpir las integraciones existentes.
Formato de respuesta y manejo de errores
- Todas las respuestas devuelven JSON con tipo de contenido: aplicación/json. Los cálculos exitosos devuelven 200 con la carga útil de resultados completa.
- Los errores de validación (campos faltantes, calificaciones fuera de rango, factor K no válido) devuelven 422 con una matriz de errores legible por humanos.
- Los errores de autenticación devuelven 401. Las claves caducadas o revocadas devuelven 403 con una URL de reactivación.
- Los errores del servidor devuelven 500 con un ID de solicitud para escalar el soporte. Todas las respuestas de error siguen la misma estructura {error, mensaje, request_id}.
Mejores prácticas de integración
Almacene en caché los cálculos repetidos localmente siempre que sea posible para minimizar las llamadas a la API. Para los flujos de trabajo de torneos, utilice el punto final por lotes en lugar de realizar solicitudes secuenciales de un solo juego. Incluya siempre el parámetro reglas_profile explícitamente en lugar de confiar en el valor predeterminado del servidor, de modo que su integración siga siendo determinista incluso cuando la API agregue nuevos perfiles.
Para el software del club y los paneles de entrenamiento, considere almacenar tanto los resultados calculados como la versión de reglas_perfil para poder auditar o recalcular más adelante si cambian las reglas de la federación. Esto es especialmente importante para los flujos de trabajo de informes oficiales donde la precisión histórica es importante.