La API pública da a los administradores de la organización acceso HTTP directo a los datos en tiempo real de tu organización — llévalos a cualquier sitio web, app, bot o automatización que pueda hacer una solicitud HTTP. Es una función del Plan Business.
La clave está acotada a tu organización — todos los endpoints operan sobre ese grupo automáticamente. URL base: https://api.ludoya.com/public/v1. Encabezado de autenticación: X-Api-Key: YOUR_KEY. Límite de velocidad: 100 solicitudes por minuto, después de lo cual recibirás un 429.
Las claves comienzan con ldy_ y tienen 36 caracteres de longitud, por lo que son fáciles de detectar en un archivo de configuración — y fáciles de escanear si alguna termina donde no debería. Trátala como una contraseña: solo del lado del servidor y revócala desde la misma página si se filtra.
A qué puedes acceder
- Ubicaciones — las ubicaciones disponibles de tu grupo y sus sitios; se usan como entrada al crear eventos
- Eventos (lectura) — eventos próximos y pasados con título, descripción, fecha/hora, zona horaria, capacidad, conteo de participantes y estado
- Eventos (escritura) — crea y actualiza eventos mediante POST y PUT, con control total sobre la ubicación, la capacidad, los permisos, la visibilidad y la imagen
- Subeventos — lista los eventos anidados dentro de un evento principal
- Participantes — agrega a alguien a un evento, cambia su asistencia o elimínalo
- Miembros — lista de miembros con perfiles de usuario y roles (Propietario, Administrador, Miembro), paginada
- Invitaciones — invita a alguien a tu grupo
- Búsqueda — busca usuarios de Ludoya y en el catálogo de juegos de mesa, para poder resolver nombres a ID antes de escribir
- Colección — colección de juegos con filtrado por propiedad, nombre, número de jugadores y lista; ordenable y paginada; cada juego incluye metadatos de BGG
- Estadísticas — estadísticas de partidas para cualquier período: totales, promedios, mejores jugadores con victorias y puntuaciones, desglose por número de jugadores, por ubicación y por juego
- Campañas (lectura) — lista las campañas del grupo con conteos de miembros y sesiones; recupera el detalle completo de la campaña, incluidos los miembros, las sesiones pasadas y los eventos programados
- Campañas (escritura) — crea campañas para el grupo y actualiza su nombre, descripción, estado y visibilidad
- Miembros de la campaña — agrega, actualiza y elimina a las personas en una campaña
Puntos de conexión
GET /locations
Devuelve las ubicaciones disponibles del grupo. Cada ubicación tiene un id, name, address opcional, capacity, un indicador isDefault y una lista spots (cada sitio tiene su propio id, name y capacity). Usa los ID de la ubicación y del sitio al crear eventos.
Inicia sesión con Ludoya
La misma página que contiene tu clave de API también convierte tu organización en un proveedor de inicio de sesión. Permite que la gente acceda a tu propio sitio web, foro o plataforma de comunidad con su cuenta de Ludoya — sin una contraseña aparte que puedan olvidar y sin una base de datos de usuarios que tengas que mantener.
Por qué vale la pena
Cuando alguien aprueba el inicio de sesión, queda vinculado a tu organización: según la política de admisión de tu grupo, o bien se convierte en miembro de inmediato (abierta), envía una solicitud para unirse para que un administrador la apruebe (solicitud para unirse), o simplemente inicia sesión sin unirse (solo con invitación). En cualquiera de los casos, aparece en el endpoint /members como cualquier otra persona — así, el inicio de sesión de tu sitio web y tu lista de miembros de Ludoya se mantienen sincronizados automáticamente.
Cómo configurarlo
Es OpenID Connect estándar, así que la mayoría de las plataformas solo necesitan una URL del emisor más un ID de cliente y su secreto. Registra tu aplicación desde la página de Public API para obtener esas credenciales, y enumera las URI de redirección que usará tu sitio — puedes registrar varias, y cada una debe coincidir con el redirect_uri que envía tu sitio carácter por carácter, incluida la barra final. Un desajuste mínimo es la razón más común por la que falla un primer intento de inicio de sesión.
- Discourse — instala el plugin de OpenID Connect, pega la URL de descubrimiento y añade las credenciales
- WordPress — cualquier plugin genérico de OpenID Connect, usando su opción "auto discover"
- Cualquier otra cosa — si es compatible con OIDC, indícale la URL del emisor y se configurará solo
Cada inicio de sesión devuelve el identificador permanente de la persona, su nombre de usuario, nombre para mostrar y avatar, y su correo electrónico. Las instrucciones completas de configuración, incluido el flujo manual, están en la guía para desarrolladores dentro de la aplicación en Desarrolladores → Iniciar sesión con Ludoya.
Para quienes inician sesión
Cualquier persona que haya usado Ludoya para iniciar sesión en algún sitio puede revisar esas conexiones en Configuración → Aplicaciones conectadas, ver cuándo se conectó y se usó por última vez cada una, y desconectar cualquiera de ellas en cualquier momento. Al desconectar, se corta inmediatamente el acceso del sitio, pero no los elimina de tu grupo.
GET /events
Devuelve eventos futuros y pasados en listas paginadas separadas.
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
onlyFuture |
booleano | true |
Establece false para devolver también eventos pasados |
Cada evento incluye: type (MEETUP o PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objeto de usuario o null), master (objeto de usuario o null). Los objetos de usuario contienen id, username, name, avatarUrl.
POST /events
Crea un evento en el grupo. Campos obligatorios: type y title. Si se omite locationId, se usa la ubicación predeterminada del grupo; si no existe, devuelve 400.
Los campos opcionales incluyen: description, locationId, spotId, gameId, parentEventId (para subeventos), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.
El campo image acepta {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Máximo 5 MB.
Devuelve {"id": "string"} con estado 201.
PUT /events/{eventId}
Actualiza un evento existente. Mismo formato de cuerpo que POST — incluye solo los campos que quieres cambiar. El solicitante debe ser el organizador del evento (la cuenta del grupo). Devuelve 202 con cuerpo vacío.
GET /events/{eventId}
Obtiene un único evento por ID, con la misma estructura que los elementos de GET /events.
GET /events/{eventId}/children
Devuelve los subeventos anidados dentro de un evento principal — las líneas temáticas o sesiones individuales de un evento de mayor envergadura. Cada subevento tiene la misma estructura que un evento normal.
Gestión de participantes
Tres endpoints te permiten gestionar la lista de asistentes de un evento desde fuera de Ludoya — útil si los registros se hacen en tu propio sitio web, o si estás importando una lista existente.
| Método | Ruta | Qué hace |
|---|---|---|
POST |
`/events/ |
GET /members
Devuelve una lista paginada de miembros.
| Parámetro | Tipo | Predeterminado |
|---|---|---|
pagination.size |
int | 50 |
pagination.offset |
int | 0 |
Cada miembro incluye: id, username, name, avatarUrl, role (OWNER, ADMIN, o MEMBER).
POST /members/invite
Invita a alguien a tu grupo. Este acepta un username directamente —no hace falta buscar el ID—, por lo que puedes incorporar miembros desde tu propio sitio o herramienta de administración.
GET /search/users y GET /search/boardgames
Los dos endpoints de búsqueda. La mayoría de las operaciones de escritura requieren un id en lugar de un nombre, y con estos puedes obtener uno.
GET /search/users
| Parámetro | Tipo | Predeterminado |
|---|---|---|
query |
cadena | requerido |
intent |
cadena | — |
pagination.size |
entero | 20 |
pagination.offset |
entero | 0 |
GET /search/boardgames
| Parámetro | Tipo | Predeterminado |
|---|---|---|
query |
cadena | requerido |
filter |
cadena | — |
pagination.size |
entero | 50 |
pagination.offset |
entero | 0 |
El filtro de juegos de mesa usa la misma forma key=value separada por punto y coma que el filtro de la colección, por lo que puedes buscar en el catálogo por número de jugadores, tiempo de juego, complejidad, año, edad o etiquetas.
GET /collection
Devuelve tu colección de juegos con filtrado, ordenación y paginación.
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
filter |
string | — | Pares key=value separados por punto y coma. Claves: ownership (OWNED, PREVIOUSLY_OWNED, PREORDERED, WISHLISTED), played (boolean), listId, nameFilter, playerCountFilterType (OFFICIAL, GOOD, BEST), playerCountFilter (number) |
groupExpansions |
boolean | true |
Agrupa las expansiones bajo su juego base |
sort |
string | — | Formato: property,direction — p. ej., name,asc |
pagination |
string | — | Formato: size,pageIndex — p. ej., 20,0 |
Respuesta: totalGames, totalExpansions, games[] — cada uno con: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.
GET /stats
Devuelve estadísticas de partidas para una ventana de tiempo configurable.
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
period |
cadena | ALL_TIME | Formato: PERIOD,date,index. Valores: ALL_TIME, ONE_YEAR, ONE_MONTH, THIRTY_DAYS, SEVEN_DAYS, ONE_DAY, CUSTOM. El index desplaza la ventana hacia atrás (0 = actual, 1 = anterior). Personalizado: CUSTOM,startDate,0,endDate |
La respuesta incluye:
- Resumen — partidas totales, tiempo de juego total/promedio, recuentos de juegos, jugadores y ubicaciones únicos
- Por jugador — partidas por persona, victorias, puntuación promedio y mejor puntuación
- Por número de jugadores — desglose de juegos de 2 jugadores, 3 jugadores, 4 jugadores, etc.
- Por ubicación — cantidad de partidas y juegos únicos por lugar
- Por juego — cantidad de partidas, tiempo de juego total/promedio y jugadores únicos por título
GET /campaigns
Devuelve una lista paginada de campañas pertenecientes al grupo.
| Parámetro | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
status |
string | — | Filtrar por estado: ACTIVE, COMPLETED o ARCHIVED |
pagination.size |
int | 50 | Elementos por página |
pagination.offset |
int | 0 | Desplazamiento |
Cada campaña incluye: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.
GET /campaigns/{campaignId}
Devuelve el detalle completo de una campaña perteneciente al grupo.
La respuesta incluye: Todos los campos de la lista, más template, description, globalNotes, globalState, members[] (cada uno con user, role, characterNotes, characterState), sessions[] y events[].
POST /campaigns
Crea una campaña para el grupo. Campos obligatorios: gameId y name. La visibilidad predeterminada es solo para miembros del grupo (ONLY_GROUP) si se omite.
Campos opcionales: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS o PRIVATE).
Devuelve {"id": "string"} con el estado 201.
PUT /campaigns/{campaignId}
Actualiza una campaña existente. Todos los campos son opcionales — incluye solo lo que quieras cambiar.
Campos opcionales: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.
Devuelve 202 con el cuerpo vacío.
Miembros de la campaña
Gestiona quién está en una campaña, de la misma manera que gestionas a los participantes de un evento.
| Método | Ruta | Qué hace |
|---|---|---|
POST |
`/campaigns/ |
Códigos de error
| Estado | Cuándo |
|---|---|
| 400 | Error de validación (falta un campo obligatorio, no se encontró ninguna ubicación, imagen no válida) |
| 401 | Falta la clave de API o no es válida |
| 403 | Acción no permitida o el grupo no está en el plan Business |
| 404 | Recurso no encontrado |
| 429 | Se superó el límite de solicitudes |
Primeros pasos
1. Generar una clave de API
- Ve a la página de perfil de tu organización
- Toca el menú (⋮) → API pública
- Toca Generar clave
- Copia tu clave de inmediato — se muestra solo una vez y no puede recuperarse de nuevo
La clave está vinculada a tu organización. Mantenla en secreto: cualquiera que tenga la clave puede leer y escribir todos los datos anteriores.
2. Revocar o volver a generar
Para revocar una clave existente, vuelve a la página de API pública y toca Revocar. Confirma el cuadro de diálogo. Cualquier sistema que use la clave antigua comenzará inmediatamente a recibir errores 401. Para emitir una nueva clave, toca Generar clave de nuevo.
Relacionado:
- Organizaciones — cuentas de organización y funciones premium
- Premium — precios del plan Business
- Integraciones — otras formas de conectar Ludoya con herramientas externas