1. Para qué sirve

JuguemosRol expone una API REST pública para que otros sitios de rol puedan mostrar su contenido y operar contra él. No es de solo lectura: un portal externo puede inscribir jugadores y crear cuentas.

Hoy la consume Territorio de Rol, que lista las partidas de su comunidad y permite inscribirse sin salir de su propio sitio. El jugador queda registrado en JuguemosRol.

2. Pedir las credenciales

Las claves se generan del lado de JuguemosRol y se entregan por pedido. Escribí desde /contacto contando qué sitio sos y qué querés hacer. Vas a recibir:

Cada clave de escritura está atada a una comunidad. La comunidad no viaja en el cuerpo del pedido: sale de la clave, así que no podés operar sobre una comunidad que no es tuya.

3. Autenticación

Base: https://juguemosrol.com/api/v1

Todo va por headers. No hay claves en la URL.

X-Api-Key:         tu-clave              (todos los endpoints)
X-Community-Token: tu-token-comunidad    (solo endpoints de comunidad)
Content-Type:      application/json      (en POST)

4. Formato de respuesta

Todas las respuestas tienen la misma forma, así que alcanza con un solo manejador:

{"ok": true,  "data": [...]}
{"ok": false, "error": "mensaje explicando qué pasó"}

5. Endpoints de lectura

6. Endpoints de escritura

Requieren la API key de escritura.

6.1 Inscribir un jugador

POST /api/v1/inscripciones/externa

{
  "email":         "jugador@ejemplo.com",   // requerido
  "partida_hash":  "a599954d64358e73",      // requerido
  "nota_jugador":  "Texto libre para el master",
  "nombre":        "Nombre del jugador",    // requerido si hay que crear la cuenta
  "pais_codigo":   "ES",                    // requerido si hay que crear la cuenta (ISO-2)
  "language_code": "es",                    // requerido si hay que crear la cuenta
  "es_suscriptor": false,
  "extra_params":  {}
}

6.2 Crear una cuenta

POST /api/v1/cuentas

{
  "email":         "jugador@ejemplo.com",   // todos requeridos
  "password":      "mínimo 8 caracteres",
  "nickname":      "identificador-unico",
  "nombre":        "Nombre del jugador",
  "pais_codigo":   "ES",
  "language_code": "es"
}

La cuenta queda pendiente hasta que la persona verifique su email, igual que en el registro web.

7. Catálogos

GET /catalogos devuelve de una sola vez todos los valores válidos que esperan los endpoints de escritura. Consultalo en vez de hardcodear listas:

{
  "ok": true,
  "data": {
    "juegos":              [ { "id": 1, "titulo": "..." } ],
    "tipos_participacion": [ ... ],
    "tipos_partida":       [ ... ],
    "tipos_experiencia":   [ ... ],
    "herramientas":        [ ... ],
    "advertencias":        [ ... ],
    "plataformas":         [ ... ],
    "paises":              [ { "id": 59, "nombre": "España", "codigo": "ES" } ],
    "languages":           [ { "id": 112, "language_code": "es", "language_name": "Spanish - español" } ]
  }
}

De ahí salen los valores de pais_codigo (el campo codigo, ISO-2) y de language_code.

8. Errores

Los mensajes de 422 están escritos para ser accionables:

{
  "ok": false,
  "error": "Para crear una cuenta nueva faltan estos campos obligatorios: nombre,
            pais_codigo, language_code. Consultá GET /api/v1/catalogos para los
            valores válidos de pais_codigo y language_code."
}

9. Ejemplo completo

Listar las partidas de tu comunidad e inscribir a alguien:

# 1. Traer las partidas de la comunidad
curl -H "X-Api-Key: TU_CLAVE_LECTURA" \
     "https://juguemosrol.com/api/v1/partidas?comunidad_id=4"

# 2. Averiguar los codigos de pais e idioma validos
curl -H "X-Api-Key: TU_CLAVE_LECTURA" \
     "https://juguemosrol.com/api/v1/catalogos"

# 3. Inscribir a un jugador
curl -X POST "https://juguemosrol.com/api/v1/inscripciones/externa" \
     -H "X-Api-Key: TU_CLAVE_ESCRITURA" \
     -H "Content-Type: application/json" \
     -d @inscripcion.json

Con inscripcion.json:

{
  "email":         "jugador@ejemplo.com",
  "partida_hash":  "a599954d64358e73",
  "nota_jugador":  "Juego desde 2015, disponible fines de semana",
  "nombre":        "Ana García",
  "pais_codigo":   "ES",
  "language_code": "es"
}