Inicio rápido

Crea un token de API de SETTO en el panel y haz tus primeras tres peticiones a la API externa con curl, JavaScript o Python.

Esta página te lleva de cero a un payload de torneo en cinco minutos: crea un token en el panel de organizador de SETTO, confírmalo con GET /v1/external/me, lista tus torneos y luego trae un torneo con sus categorías incrustadas. Cada petición es un GET simple con una cabecera Authorization: Bearer — sin SDK, sin baile de OAuth, sin client secret.

Antes de empezar

Necesitas una cuenta de SETTO. Un token personal alcanza todos los torneos que administras; para darle a un sistema solo los torneos de una organización, crea un token de organización — consulta Dos tipos de token. ¿Vas a conectar un asistente de IA? claude.ai, ChatGPT, Codex y Claude Code pueden entrar con tu cuenta de SETTO, sin token.

Crea un token de API

En app.setto.io, abre Configuración → Tokens de API, deja el selector de cuenta u organización en Personal (o elige una organización) y selecciona Crear token. Ponle un nombre que reconozcas después (Website widget, Season export, …), opcionalmente elige una expiración de 30, 90 o 365 días, y confirma.

El secreto se muestra exactamente una vez

SETTO guarda solo un hash del token. El valor completo setto_live_… aparece en el diálogo justo después de crearlo y nunca más — cópialo a tu gestor de secretos antes de cerrarlo. Si lo pierdes, revoca el token y crea uno nuevo.

Puedes tener hasta 10 tokens personales activos, y una organización hasta 10 tokens de organización activos. Un token lee (scopes: ["read"]) a menos que marques más en Permisos: «Gestionar torneos» le agrega las escrituras de configuración de torneos — crear torneos y categorías, inscribir equipos, «Sustitución», «Baja», el formato, los grupos y el cuadro — como manage, «Cargar resultados» le agrega cargar y borrar resultados como results, «Programar partidos» le agrega fijar horarios y canchas de los partidos como schedule (scopes: ["read", "schedule"]), y los demás permisos están en Qué puede cambiar un token. Cualquier token se puede revocar en cualquier momento desde esa misma lista.

Confirma el token

GET /v1/external/me es la forma más barata de comprobar que un token funciona. Te dice de quién es el token (owner), cuándo se creó, cuándo expira y cuál es tu límite de uso.

export SETTO_API_TOKEN="setto_live_YOUR_TOKEN_HERE"

curl -s https://api.setto.io/v1/external/me \
  -H "Authorization: Bearer $SETTO_API_TOKEN"

200 OK

{
  "owner": {
    "type": "user",
    "idx": "2a7e4c91-0b3d-4f58-9e16-c5d8a2f4b073",
    "name": "Ana López"
  },
  "organization": null,
  "token": {
    "idx": "b8e3f107-5c92-4d6a-8e71-0a4c9d2b3f65",
    "name": "Website widget",
    "prefix": "setto_live_9f2ca",
    "scopes": ["read"],
    "createdAt": "2026-09-01T16:04:22.113Z",
    "expiresAt": null,
    "lastUsedAt": "2026-09-17T09:12:44.005Z"
  },
  "rateLimit": { "limit": 120, "windowSeconds": 60 }
}

Ese es un token personal: owner.type es "user" y organization es null. Un token de organización responde owner.type: "organization" y llena organization con el idx, name, slug, avatar y website de la organización.

Un 401 aquí significa que falta la cabecera o que el token es incorrecto — consulta Errores.

Lista tus torneos

GET /v1/external/tournaments devuelve una página de torneos ordenados por startDate descendente, del más reciente al más antiguo.

curl -s -G https://api.setto.io/v1/external/tournaments \
  -H "Authorization: Bearer $SETTO_API_TOKEN" \
  -d status=IN_PROGRESS \
  -d sport=PADEL \
  -d limit=5

200 OK (recortado)

{
  "data": [
    {
      "idx": "3c9b7f52-6d41-4a8e-b1f0-2e7d5c9a4b18",
      "slug": "torneo-apertura-2026",
      "name": "Torneo Apertura 2026",
      "type": "TOURNAMENT",
      "sport": "PADEL",
      "status": "IN_PROGRESS",
      "startDate": "2026-09-18T00:00:00.000Z",
      "endDate": "2026-09-20T00:00:00.000Z",
      "timezone": "America/Monterrey",
      "publicUrl": "https://www.setto.io/t/torneo-apertura-2026",
      "organization": {
        "idx": "6f1d9c2e-4a7b-4f3d-9d2c-8b5e1a0f7c43",
        "name": "Club Padel Monterrey",
        "slug": "club-padel-monterrey"
      }
    }
  ],
  "meta": { "limit": 5, "offset": 0, "total": 1 }
}

Guarda el idx — es el identificador que toman todos los demás endpoints.

Trae un torneo con sus categorías

Las relaciones son opcionales. Pídelas con populate, una lista separada por comas. GET /v1/external/tournaments/{idx} usa por defecto club,divisions; pedir solo divisions mantiene el payload pequeño.

curl -s -G \
  https://api.setto.io/v1/external/tournaments/3c9b7f52-6d41-4a8e-b1f0-2e7d5c9a4b18 \
  -H "Authorization: Bearer $SETTO_API_TOKEN" \
  -d populate=divisions