API pública

La API pública dona als administradors de l'organització accés HTTP directe a les dades en temps real de la teva organització — porta-les a qualsevol lloc web, app, bot o automatització que pugui fer una sol·licitud HTTP. És una funció del Pla Business.

La clau està restringida a la teva organització — tots els endpoints operen sobre aquest grup automàticament. URL base: https://api.ludoya.com/public/v1. Capçalera d'autenticació: X-Api-Key: YOUR_KEY. Límit de freqüència: 100 sol·licituds per minut, passat aquest límit, rebràs un 429.

Les claus comencen amb ldy_ i tenen 36 caràcters de longitud, de manera que són fàcils de detectar en un fitxer de configuració — i fàcils d'escanejar si alguna acaba on no hauria. Tracta-la com una contrasenya: només al servidor, i revoca-la des de la mateixa pàgina si es filtra.

A què pots accedir

• Ubicacions — les ubicacions disponibles del teu grup i els seus llocs; s'utilitzen com a entrada en crear esdeveniments
• Esdeveniments (lectura) — esdeveniments propers i passats amb títol, descripció, data/hora, zona horària, capacitat, recompte de participants i estat
• Esdeveniments (escriptura) — crea i actualitza esdeveniments mitjançant POST i PUT, amb control total sobre la ubicació, la capacitat, els permisos, la visibilitat i la imatge
• Subesdeveniments — llista els esdeveniments imbricats dins d'un esdeveniment pare
• Participants — afegeix algú a un esdeveniment, canvia la seva assistència o elimina'l
• Membres — llista de membres amb perfils d'usuari i rols (Propietari, Administrador, Membre), paginada
• Invitacions — convida algú al teu grup
• Cerca — cerca usuaris de Ludoya i el catàleg de jocs de taula, per poder resoldre noms a ID abans d'escriure
• Col·lecció — col·lecció de jocs amb filtratge per propietat, nom, nombre de jugadors i llista; ordenable i paginada; cada joc inclou metadades de BGG
• Estadístiques — estadístiques de partides per a qualsevol període: totals, mitjanes, millors jugadors amb victòries i puntuacions, desglossaments per nombre de jugadors, per ubicació i per joc
• Campanyes (lectura) — llista les campanyes del grup amb recomptes de membres i sessions; recupera el detall complet de la campanya, incloent-hi els membres, les sessions passades i els esdeveniments programats
• Campanyes (escriptura) — crea campanyes per al grup i n'actualitza el nom, la descripció, l'estat i la visibilitat
• Membres de la campanya — afegeix, actualitza i elimina les persones d'una campanya

Punts de connexió

GET /locations

Retorna les ubicacions disponibles del grup. Cada ubicació té un id, name, address opcional, capacity, un indicador isDefault i una llista spots (cada lloc té el seu propi id, name i capacity). Utilitza els ID d'ubicació i de lloc en crear esdeveniments.

Inicia la sessió amb Ludoya

La mateixa pàgina que conté la teva clau d'API també converteix la teva organització en un proveïdor d'inici de sessió. Permet que la gent iniciï la sessió al teu propi lloc web, fòrum o plataforma comunitària amb el seu compte de Ludoya — sense una contrasenya a part que puguin oblidar, i sense una base de dades d'usuaris que hagis de gestionar.

Per què val la pena

Quan algú aprova l'inici de sessió, queda vinculat a la teva organització: segons la política d'admissió del teu grup, o bé es converteix en membre de seguida (oberta), envia una sol·licitud per unir-se perquè un administrador l'aprovi (sol·licitud per unir-se), o simplement inicia la sessió sense unir-se (només amb invitació). En qualsevol cas, apareix a l'endpoint /members com qualsevol altra persona — així, l'inici de sessió del teu lloc web i la teva llista de membres de Ludoya es mantenen sincronitzats automàticament.

Com configurar-ho

És OpenID Connect estàndard, així que la majoria de plataformes només necessiten una URL de l'emissor més un ID de client i el seu secret. Registra la teva aplicació des de la pàgina de Public API per obtenir aquestes credencials, i enumera les URI de redirecció que farà servir el teu lloc — en pots registrar diverses, i cadascuna ha de coincidir amb el redirect_uri que envia el teu lloc caràcter per caràcter, inclosa la barra final. Un desajust mínim és la raó més habitual per la qual falla un primer intent d'inici de sessió.

• Discourse — instal·la el connector d'OpenID Connect, enganxa la URL de descobriment i afegeix les credencials
• WordPress — qualsevol connector genèric d'OpenID Connect, fent servir la seva opció "auto discover"
• Qualsevol altra cosa — si és compatible amb OIDC, indica-li la URL de l'emissor i es configurarà automàticament

Cada inici de sessió retorna l'identificador permanent de la persona, el seu nom d'usuari, nom per mostrar i avatar, i el seu correu electrònic. Les instruccions completes de configuració, inclòs el flux manual, són a la guia per a desenvolupadors dins de l'aplicació a Desenvolupadors → Inicia la sessió amb Ludoya.

Per a les persones que inicien la sessió

Qualsevol persona que hagi utilitzat Ludoya per iniciar la sessió en algun lloc pot revisar aquestes connexions a Configuració → Aplicacions connectades, veure quan es va connectar cadascuna i quan es va utilitzar per última vegada, i desconnectar-ne qualsevol en qualsevol moment. En desconnectar, es talla immediatament l'accés del lloc, però no els elimina del teu grup.

GET /events

Retorna esdeveniments futurs i passats en llistes paginades separades.

Cada esdeveniment inclou: type (MEETUP o PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objecte d'usuari o null), master (objecte d'usuari o null). Els objectes d'usuari contenen id, username, name, avatarUrl.

POST /events

Crea un esdeveniment al grup. Camps obligatoris: type i title. Si s'omet locationId, s'utilitza la ubicació predeterminada del grup; si no n'hi ha, retorna 400.

Els camps opcionals inclouen: description, locationId, spotId, gameId, parentEventId (per a subesdeveniments), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

El camp image accepta {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Màxim 5 MB.

Retorna {"id": "string"} amb l'estat 201.

PUT /events/{eventId}

Actualitza un esdeveniment existent. Mateix format de cos que POST — inclou només els camps que vols canviar. El sol·licitant ha de ser l'organitzador de l'esdeveniment (el compte del grup). Retorna 202 amb el cos buit.

GET /events/{eventId}

Obté un únic esdeveniment per ID, amb la mateixa estructura que els elements de GET /events.

GET /events/{eventId}/children

Llista els subesdeveniments niuats dins d'un esdeveniment principal — les línies temàtiques o sessions individuals d'una trobada de més envergadura. Cada subesdeveniment té la mateixa estructura que un esdeveniment normal.

Gestió de participants

Tres endpoints et permeten gestionar la llista d'assistents d'un esdeveniment des de fora de Ludoya — útil si les inscripcions es fan al teu propi lloc web, o si estàs important una llista existent.

GET /members

Retorna una llista de membres paginada.

Cada membre inclou: id, username, name, avatarUrl, role (OWNER, ADMIN o MEMBER).

POST /members/invite

Convida algú al teu grup. Aquest accepta un username directament — no cal cercar l’ID —, de manera que pots incorporar membres directament des del teu propi lloc web o eina d’administració.

GET /search/users i GET /search/boardgames

Els dos endpoints de cerca. La majoria d'operacions d'escriptura necessiten un id en lloc d'un nom, i amb aquests el pots obtenir.

GET /search/users

GET /search/boardgames

El filtre de jocs de taula utilitza la mateixa forma key=value separada per punt i coma que el filtre de la col·lecció, de manera que pots cercar al catàleg per nombre de jugadors, temps de joc, complexitat, any, edat o etiquetes.

GET /collection

Retorna la teva col·lecció de jocs amb filtratge, ordenació i paginació.

Resposta: totalGames, totalExpansions, games[] — cadascun amb: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Retorna estadístiques de partides per a una finestra de temps configurable.

La resposta inclou:

• Resum — total de partides, temps de joc total/mitjà, recompte de jocs únics, jugadors únics i ubicacions úniques
• Per jugador — partides per persona, victòries, puntuació mitjana i millor puntuació
• Per nombre de jugadors — desglossament de jocs de 2 jugadors, 3 jugadors, 4 jugadors, etc.
• Per ubicació — nombre de partides i jocs únics per lloc
• Per joc — nombre de partides, temps de joc total/mitjà i jugadors únics per títol

GET /campaigns

Retorna una llista paginada de campanyes que pertanyen al grup.

Cada campanya inclou: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Retorna el detall complet d'una campanya que pertany al grup.

La resposta inclou: Tots els camps de la llista, a més de template, description, globalNotes, globalState, members[] (cadascun amb user, role, characterNotes, characterState), sessions[] i events[].

POST /campaigns

Crea una campanya per al grup. Camps obligatoris: gameId i name. La visibilitat per defecte és només per als membres del grup (ONLY_GROUP) si s'omet.

Camps opcionals: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS o PRIVATE).

Retorna {"id": "string"} amb l'estat 201.

PUT /campaigns/{campaignId}

Actualitza una campanya existent. Tots els camps són opcionals — inclou només el que vulguis canviar.

Camps opcionals: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Retorna 202 amb el cos buit.

Membres de la campanya

Gestiona qui forma part d'una campanya, de la mateixa manera que gestiones els participants d'un esdeveniment.

Codis d'error

Primers passos

1. Generar una clau d'API

1. Ves a la pàgina de perfil de la teva organització
2. Toca el menú (⋮) → API pública
3. Toca Generar clau
4. Copia la teva clau immediatament — es mostra només una vegada i no es pot tornar a recuperar

La clau està vinculada a la teva organització. Mantén-la en secret: qualsevol amb la clau pot llegir i escriure totes les dades anteriors.

2. Revocar o tornar a generar

Per revocar una clau existent, torna a la pàgina de l'API pública i toca Revocar. Confirma el diàleg. Qualsevol sistema que utilitzi la clau antiga començarà immediatament a rebre errors 401. Per emetre una clau nova, toca Generar clau de nou.

Relacionat:

• Organitzacions — comptes d'organització i funcions premium
• Premium — preus del pla Business
• Integracions — altres maneres de connectar Ludoya amb eines externes