API pública de resultados (v1)
Los organizadores externos envían los resultados de una sección y cualquiera lee los publicados. La API vive bajo /api/v1.
Autenticación
Un propietario o administrador de la organización crea una clave en la consola del organizador. La clave se muestra una vez y se guarda como hash; al revocarla deja de funcionar de inmediato. Envíala en cada envío en la cabecera X-Api-Key.
X-Api-Key: tcsa_AbCdEfGh_0123456789abcdefghijklmnopqrstuvwx
La misma clave se acepta como token bearer:
Authorization: Bearer tcsa_AbCdEfGh_0123456789abcdefghijklmnopqrstuvwxEnviar resultados
Un envío nombra una sección de un evento de la organización de la clave. La sección debe ser de las que muestran un archivo TRF (no de las emparejadas aquí). Un envío reemplaza lo que la sección muestra, igual que un archivo confirmado en la consola.
Archivo TRF
El cuerpo de la petición es el archivo TRF. Un archivo que el importador rechaza responde 422 y no guarda nada; el arreglo problems nombra el motivo sin datos de jugadores.
POST /api/v1/organizer/sections/{sectionId}/trf
Content-Type: text/plain
Content-Disposition: attachment; filename=open-naco-round5.trf
<the TRF file's bytes>
JSON de clasificación
El JSON lleva solo la clasificación: jugadores con su número inicial, nombre, puntos y puesto, y los datos FIDE opcionales. Reemplaza la clasificación de la sección; no lleva emparejamientos. Los nombres tienen como máximo 33 caracteres, los ID FIDE 11 dígitos y los puntos 100.
POST /api/v1/organizer/sections/{sectionId}/standings
Content-Type: application/json
{
"tournamentName": "Open Naco 2026",
"players": [
{
"startRank": 1,
"name": "Perez, Juan",
"fideId": "6400000",
"title": "GM",
"rating": 2450,
"federation": "DOM",
"points": 7.5,
"rank": 1
}
]
}
Un JSON rechazado responde 422 con problems: json, players, startRank, name, fideId, title, federation, rating, points o rank.
Límites e idempotencia
Una clave hace como máximo 60 peticiones por minuto; las siguientes responden 429 con Retry-After (y X-RateLimit-Limit y X-RateLimit-Remaining en cada respuesta autenticada). Un archivo TRF es de 2 MiB como máximo y un JSON de clasificación de 1 MiB.
Enviar otra vez el mismo archivo o la misma clasificación responde unchanged y no cambia nada. Cada envío autenticado escribe una fila de auditoría, incluso uno rechazado; una petición sin una clave válida no escribe ninguna, y un envío rechazado no guarda ningún resultado.
Estados
El cuerpo de cada respuesta nombra su estado en el campo status.
| Estado | Significado |
|---|---|
200 accepted | Los resultados se guardaron; la sección los muestra, marcados como no oficiales hasta que un propietario o administrador los confirme. |
200 unchanged | La sección ya muestra exactamente este envío; nada cambió. |
401 | Falta la clave, no es nuestra o está revocada. |
403 notAllowed | El ámbito no puede enviar para esta sección. Una clave de la API siempre puede, así que es una salvaguarda: una sección de otra organización, o una desconocida, responde 404. |
409 native | La sección se empareja aquí: no admite archivos ni clasificaciones. |
413 | El envío supera el límite; no se guardó nada. |
415 | El endpoint de clasificación espera Content-Type: application/json. |
422 invalid | El archivo o el JSON no son válidos; no se guardó nada. |
429 | La clave superó su minuto; espera los segundos de Retry-After. |
404 notFound | La organización de la clave no tiene esa sección. |
Resultados no oficiales
Los resultados enviados por la API se marcan como no oficiales en las páginas públicas. Un propietario o administrador de la organización los confirma en el historial de archivos de la sección, y la marca desaparece.
Leer resultados publicados
No hace falta clave. Los eventos son los publicados, los más recientes primero, 20 por página (?page=N); un borrador, una página que nuestro personal retiró y cualquier dato personal nunca se devuelven. Todos los endpoints están bajo el prefijo de versión /api/v1.
GET /api/v1/public/events?page=1
GET /api/v1/public/events/{eventId}
GET /api/v1/public/events/{eventId}/sections/{sectionId}/standings
{
"page": 1,
"pages": 3,
"total": 41,
"events": [
{ "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" }
]
}
Un evento publicado por id, con sus secciones; un borrador, una página retirada o un id desconocido responde 404.
{
"event": { "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" },
"sections": [
{ "id": "…", "slug": "open", "name": "Open", "source": "trf" }
]
}
La clasificación de la sección lleva el evento, la sección (con sus rondas y la marca de no oficial), sus desempates y sus jugadores: número inicial, nombre, ID FIDE, título, rating, federación, puntos, puesto y si se retiraron. Nunca el año de nacimiento, el sexo, una cuenta ni un correo.
{
"event": { "id": "…", "path": "DOM/2026/12/open-naco", "name": "Open Naco 2026",
"startsOn": "2026-12-05", "endsOn": "2026-12-06", "location": "Santo Domingo" },
"section": { "id": "…", "slug": "open", "name": "Open", "source": "trf",
"rounds": 5, "unofficial": false },
"tieBreaks": ["BH", "BH-C1"],
"players": [
{ "startRank": 1, "name": "Perez, Juan", "fideId": "6400000", "title": "GM",
"rating": 2450, "federation": "DOM", "points": 7.5, "rank": 1, "withdrawn": false }
]
}Lo que nunca devolvemos
La API lee las mismas páginas públicas que muestra el sitio. No contiene datos personales más allá de lo que muestran esas páginas, y una clave nunca se registra: nuestros registros llevan solo identificadores.