Modelo de datos
El árbol de dominio de SETTO — organización, torneo, categoría, ronda, grupo, cuadro y partido — más las convenciones de identificadores y los valores de enum sobre los que vas a ramificar.
Todo lo que devuelve la API externa cuelga de un mismo árbol: una organización posee torneos; un torneo tiene categorías (divisions) y equipos; una categoría tiene rondas; una ronda contiene grupos (pools, con clasificación) para el juego de todos contra todos y cuadros (draws) para la eliminación directa; ambos terminan conteniendo partidos, y un partido terminado tiene un marcador (score) con sus sets. Aprende esta forma una vez y los seis endpoints dejan de parecer seis cosas sin relación.
El árbol
En prosa:
- Una Organization posee torneos. Tu token está ligado a exactamente una.
- Un Tournament es una competencia. Lleva el formato (
type), el deporte, elstatusdel ciclo de vida, las fechas y unapublicUrl. - Una Division es lo que organizadores y jugadores llaman categoría: un
segmento por nivel y rama dentro del torneo (
Cuarta Fuerza Varonil). Es dueña de las rondas y del precio. - Un Round es una fase — juego de grupos o una etapa de eliminación.
- Un Pool es un grupo dentro de una ronda de todos contra todos; contiene los equipos de ese grupo y su clasificación (standings).
- Un Draw es un cuadro. Contiene draw rounds (
Quarterfinals,Semifinals, …) en suorder, y cada draw round contiene sus partidos. - Un Game es un partido. Los partidos terminados llevan un score, que a su vez lleva sus sets.
- Un Team es una inscripción registrada: una pareja en dobles, un jugador único en singles, y en las ligas por equipos una escuadra ligada a un league team.
Identificadores
Cada recurso expone un UUID v4 como idx. Ese es el id que pasas en una ruta
(/v1/external/tournaments/{idx}) y el id que guardas de tu lado. Las llaves
primarias numéricas que SETTO usa internamente nunca se exponen.
Los torneos llevan dos identificadores extra:
| Campo | Ejemplo | Uso |
|---|---|---|
slug | torneo-apertura-2026 | Legible, único, estable |
publicUrl | https://www.setto.io/t/torneo-apertura-2026 | Página pública canónica, lista para enlazar |
Los endpoints toman idx, no slug. Guarda el idx de la llamada de listado;
usa el slug para mostrar y la publicUrl para enlazar.
Torneo
| Campo | Notas |
|---|---|
type | Formato de competencia — ver abajo |
sport | PADEL, TENNIS o PICKLEBALL |
status | Ciclo de vida — ver abajo |
startDate, endDate | Marcas de tiempo ISO 8601 en UTC |
timezone | Zona IANA en la que se armó el calendario (America/Monterrey), nullable |
isPublic | Si la página pública es accesible — false no la oculta de la API |
isFormatComplete | Si el organizador terminó de configurar el formato |
matchDays | Número de jornadas, para torneos con forma de liga |
standingColumns | Qué estadísticas muestra el organizador en la tabla de clasificación |
publicUrl | https://www.setto.io/t/{slug} |
organization | { idx, name, slug } — siempre presente |
type
Los cuatro formatos que te vas a encontrar más seguido:
| Valor | Forma |
|---|---|
TOURNAMENT | Un evento único: fase de grupos y/o un cuadro |
LEAGUE | Una temporada de jornadas entre parejas |
TEAM_LEAGUE | Una temporada entre escuadras; una ronda puede tener division: null |
INDIVIDUAL_LEAGUE | Una temporada entre jugadores individuales |
Los formatos especializados (Americano, express/lucky-loser y las ligas
individuales de pickleball) llevan sus propios valores de type. Trata type
como una cadena abierta: ramifica sobre los valores que te importen y deja pasar
el resto, en lugar de dar por hecho que el conjunto está cerrado.
status
El ciclo de vida corre en una sola dirección:
DRAFT → UPCOMING → IN_PROGRESS → COMPLETED → ARCHIVEDLos cinco se devuelven. Los torneos DRAFT y ARCHIVED son visibles para tu
token aunque el sitio público los oculte — fíltralos con el parámetro de consulta
status, o descártalos del lado del cliente, antes de renderizar nada público.
Categoría (division)
| Campo | Notas |
|---|---|
name | Cuarta Fuerza Varonil |
number | Orden de despliegue; las listas se ordenan por él, ascendente |
color | Color hexadecimal que eligió el organizador, usado en toda la UI de SETTO |
isDoubles | true para parejas, false para singles |
isVisible | false significa que el organizador ocultó esta categoría en el sitio público |
price | Precio de inscripción de esta categoría, nullable |
minParticipants, maxParticipants, maxRegistrations | Cupo, todos nullable |
tournament | Referencia inversa { idx } |
Lo oculto se devuelve, no se filtra
Una categoría oculta regresa con isVisible: false en lugar de omitirse. El
trabajo de la API es decirte la verdad; decidir qué mostrar es tuyo. Lo mismo
aplica a las rondas.
Ronda
| Campo | Notas |
|---|---|
name | Pool Play, Playoffs o Qualifiers |
type | ROUND_ROBIN_ROUND, SINGLE_ELIMINATION_ROUND o QUALIFIERS_ROUND |
number | Orden dentro de la categoría |
isVisible | Misma semántica que en una categoría |
isSetup | Si el organizador ya generó los partidos de la ronda |
numberOfSets, proSets, playAllSets, pointsPerSet | Reglas de puntuación |
drawSize, numQualifiers, placements | Dimensiones del cuadro |
division | { idx, name } — nullable: una ronda de TEAM_LEAGUE puede abarcar todo el torneo |
Una ronda de todos contra todos llena pools; una ronda de eliminación directa
llena draws. Muchas rondas llenan tanto games (la lista plana) como la
estructura anidada del cuadro — así que el mismo partido puede aparecer dos veces
en un payload, una bajo games y otra bajo draws[].rounds[].games[]. Elimina
duplicados por game.idx.
Grupo, clasificación y estadísticas de equipo
Un pool es un grupo: { idx, name, number }, más teams y standings
cuando los populas. Una standing lleva rank, awardedPoints, su referencia
team, y un objeto teamStats con points, wins, losses, ties,
forfeits, pointsFor / pointsAgainst, setsPointsFor /
setsPointsAgainst y las dos diferencias calculadas.
Sobre rank
rank es el rango almacenado, tal como SETTO lo calculó por última vez. El
sitio público aplica encima el head-to-head y los demás desempates
configurados al renderizar una tabla de clasificación, así que una tabla que
armes solo con rank puede diferir de la de setto.io. Si necesitas paridad
exacta, ordena con las reglas de desempate del propio torneo
(populate=rankedTiebreakRules en el torneo) en lugar de hacerlo por rank.
Cuadro y ronda de cuadro
Un draw es un cuadro: { idx, placement }. placement distingue el cuadro
principal de los cuadros de consolación y de tercer lugar. Sus draw rounds
llevan un label (Quarterfinals, Semifinals, Final) y un order; ordena
por order para acomodar el cuadro de izquierda a derecha.
Partido
| Campo | Notas |
|---|---|
number, displayNumber | Numeración del partido; displayNumber es la que muestran los organizadores |
status | UPCOMING, FINISHED, CANCELLED, FORFEIT o BYE |
time | Hora programada de inicio, ISO 8601 en UTC, nullable |
courtNumber, court | Número de cancha y, cuando se popula, el objeto de la cancha |
matchDay | Número de jornada, para ligas |
homeTeam, awayTeam, winner | Referencias { idx, name }, cada una nullable |
homeTeamDetails, awayTeamDetails | Descripción del hueco por definir — ver abajo |
score | { home, away, sets[] } cuando se popula |
isRetirement | Si el partido terminó por retiro |
Huecos por definir
En un cuadro, un partido suele existir antes de que se conozcan sus
participantes. Entonces homeTeam es null y homeTeamDetails describe de
dónde va a salir el equipo:
{
"label": "Winner of Game 3",
"teamNumber": null,
"poolNumber": null,
"poolRank": null,
"sourceGameNumber": 3,
"sourceResult": "WINNER"
}label es una cadena almacenada en inglés. Si tu sitio no está en inglés,
renderiza sourceGameNumber y sourceResult por tu cuenta en lugar de imprimir
label.
Marcador y sets
{
"idx": "1b9d7c36-4e58-40af-92c1-6d3f8a05b7e2",
"home": 2,
"away": 1,
"sets": [
{ "idx": "…", "number": 1, "home": 6, "away": 4, "isTieBreak": false },
{ "idx": "…", "number": 2, "home": 3, "away": 6, "isTieBreak": false },
{ "idx": "…", "number": 3, "home": 7, "away": 5, "isTieBreak": false }
]
}score.home / score.away son sets ganados, no puntos. Los puntos por set
viven en sets[], ordenados por number.
Equipo
| Campo | Notas |
|---|---|
name | Álvarez / Peña para una pareja, el nombre del jugador en singles |
seed, seedNumber | Siembra; nullable, y ordenada con los nulos al final en las respuestas de lista |
division | { idx, name }, nullable |
players | [{ idx, firstName, lastName, avatar }] cuando se popula — nunca datos de contacto |
captainProfileIdx | El idx del perfil de jugador del capitán, cuando se popula |
leagueTeam | { idx, name, color, logo, position, pointsAdjustment } para ligas por equipos |
isWildCard, qualifierStatus, drawAssignment | Control de wildcards y clasificados |
picture, club, ranking, description | Campos opcionales de presentación |
En un TEAM_LEAGUE, un equipo pertenece a un league team — la escuadra
(Alemania, Brasil) que acumula puntos a lo largo de la temporada.
Fechas y zonas horarias
Cada marca de tiempo es ISO 8601 en UTC con sufijo Z
(2026-09-18T17:00:00.000Z). El campo timezone del torneo te dice en qué zona
IANA armó el organizador el calendario; conviértela antes de mostrar una hora de
inicio, o un partido de las 19:00 en Monterrey se leerá como la 01:00 del día
siguiente.
Autenticación
Cómo funcionan los tokens de API de SETTO — la cabecera bearer, los prefijos live y test, el alcance por organización, expiración, rotación y revocación, y la diferencia entre 401 y 403.
Populate
Cómo el parámetro de consulta populate incrusta relaciones, la lista blanca exacta por endpoint, los valores por defecto de cada endpoint y las reglas para las rutas anidadas.