Nyilvános API

A Nyilvános API közvetlen HTTP-hozzáférést ad a szervezet adminisztrátorainak a szervezeted élő adataihoz — beviheted bármely weboldalba, appba, botba vagy automatizálásba, amely képes HTTP-kérést küldeni. A Business csomag funkciója.

A kulcs a szervezetedhez van kötve — minden végpont automatikusan azon a csoporton működik. Alap URL: https://api.ludoya.com/public/v1. Hitelesítési fejléc: X-Api-Key: YOUR_KEY. Kérésszám-korlát: percenként 100 kérés, ezután 429 választ kapsz.

A kulcsok ldy_-vel kezdődnek és 36 karakter hosszúak, így könnyű őket kiszúrni egy konfigurációs fájlban — és könnyű rájuk keresni is, ha valaha oda kerülnek, ahova nem kellene. Kezeld úgy, mint egy jelszót: csak szerveroldalon használd, és ugyanazon az oldalon vond vissza, ha kiszivárog.

Mihez férhetsz hozzá

• Helyszínek — a csoportod elérhető helyszínei és azok helyei; események létrehozásakor bemenetként használhatók
• Események (olvasás) — közelgő és múltbeli események címmel, leírással, dátummal/idővel, időzónával, kapacitással, résztvevőszámmal és státusszal
• Események (írás) — események létrehozása és frissítése POST és PUT segítségével, teljes kontrollal a helyszín, kapacitás, jogosultságok, láthatóság és kép felett
• Al-események — a szülőeseménybe ágyazott események listázása
• Résztvevők — valakit hozzáadni egy eseményhez, módosítani a részvételét vagy eltávolítani
• Tagok — taglista felhasználói profilokkal és szerepkörökkel (Tulajdonos, Admin, Tag), lapozható
• Meghívások — valakit meghívni a csoportodba
• Keresés — Ludoya-felhasználók és a társasjáték-katalógus keresése, hogy írás előtt a neveket azonosítókra tudd feloldani
• Gyűjtemény — játékgyűjtemény szűrés tulajdon, név, játékosszám és lista szerint; rendezhető és lapozható; minden játék tartalmaz BGG metaadatokat
• Statisztikák — játszma statisztikák bármely időszakra: összesítések, átlagok, top játékosok győzelmekkel és pontszámokkal, játékosszámonkénti bontások, helyszínenként és játékonként
• Kampányok (olvasás) — a csoport kampányainak listázása tag- és alkalomszámokkal; teljes kampányrészletek lekérése, beleértve a tagokat, a korábbi alkalmakat és az ütemezett eseményeket
• Kampányok (írás) — kampányok létrehozása a csoport számára, és a nevük, leírásuk, állapotuk és láthatóságuk frissítése
• Kampánytagok — emberek hozzáadása, frissítése és eltávolítása egy kampányban

Végpontok

GET /locations

Visszaadja a csoport elérhető helyszíneit. Minden helyszínnek van id, name, opcionális address, capacity, egy isDefault jelzője és egy spots tömbje (minden helynek saját id, name és capacity értéke van). Események létrehozásakor a helyszín- és helyazonosítókat használd.

Bejelentkezés a Ludoyával

Ugyanaz az oldal, amely az API-kulcsodat tartalmazza, a szervezetedet is bejelentkezési szolgáltatóvá teszi. Engedd, hogy az emberek a saját webhelyedre, fórumodra vagy közösségi platformodra a Ludoya-fiókjukkal jelentkezzenek be — külön jelszó nélkül, amit elfelejthetnek, és anélkül, hogy neked felhasználói adatbázist kellene működtetned.

Miért éri meg

Amikor valaki jóváhagyja a bejelentkezést, kapcsolatba kerül a szervezeteddel: a csoportod csatlakozási szabályzatától függően vagy azonnal taggá válnak (nyitott), csatlakozási kérelmet nyújtanak be egy admin jóváhagyására (csatlakozási kérelem), vagy egyszerűen bejelentkeznek csatlakozás nélkül (csak meghívással). Akárhogy is, megjelennek a /members végponton, mint bárki más — így a webhelyed bejelentkezése és a Ludoya-taglistád automatikusan szinkronban marad.

Beállítás

Szabványos OpenID Connect, így a legtöbb platformnak nincs másra szüksége, mint egy kibocsátó (issuer) URL-re, valamint egy kliensazonosítóra és titokra. Regisztráld az alkalmazásodat a Public API oldaláról, hogy megkapd ezeket a hitelesítő adatokat, és sorold fel azokat az átirányítási URI-kat, amelyeket a webhelyed használni fog — több is regisztrálható, és mindegyiknek karakterről karakterre meg kell egyeznie azzal a redirect_uri-val, amit a webhelyed küld, a záró perjellel együtt. Egy kis eltérés az első bejelentkezési kísérlet meghiúsulásának leggyakoribb oka.

• Discourse — telepítsd az OpenID Connect bővítményt, illeszd be a felderítési URL-t, add hozzá a hitelesítő adatokat
• WordPress — bármely általános OpenID Connect bővítmény, a "auto discover" opcióját használva
• Bármi más — ha támogatja az OIDC-t, irányítsd a kibocsátó URL-re, és magától beáll

Minden bejelentkezés visszaadja a személy állandó azonosítóját, felhasználónevét, megjelenített nevét és avatarját, valamint az e-mail-címét. A teljes beállítási útmutató, beleértve a kézi folyamatot is, az alkalmazáson belüli fejlesztői útmutatóban található: Fejlesztők → Bejelentkezés a Ludoyával.

A bejelentkezőknek

Bárki, aki a Ludoyát használta bejelentkezésre valahol, áttekintheti ezeket a kapcsolatokat a Beállítások → Csatlakoztatott alkalmazások alatt, megnézheti, mikor csatlakozott és mikor használták utoljára mindegyiket, és bármelyiket bármikor lekapcsolhatja. A lekapcsolás azonnal megszünteti a webhely hozzáférését, de nem távolítja el őket a csoportodból.

GET /events

A jövőbeli és múltbeli eseményeket külön, lapozható listákban adja vissza.

Minden esemény tartalmazza: type (MEETUP vagy PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (felhasználói objektum vagy null), master (felhasználói objektum vagy null). A felhasználói objektumok a következőket tartalmazzák: id, username, name, avatarUrl.

POST /events

Létrehoz egy eseményt a csoportban. Kötelező mezők: type és title. Ha a locationId hiányzik, a csoport alapértelmezett helyszíne kerül felhasználásra; ha nincs ilyen, 400-at ad vissza.

Opcionális mezők: description, locationId, spotId, gameId, parentEventId (al-eseményekhez), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Az image mező {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}-t fogad el. Legfeljebb 5 MB.

{"id": "string"}-t ad vissza 201-es státusszal.

PUT /events/{eventId}

Egy meglévő eseményt frissít. Ugyanaz a törzsformátum, mint a POST-nál — csak azokat a mezőket add meg, amelyeket módosítani szeretnél. A hívónak az esemény szervezőjének (a csoport fiókjának) kell lennie. 202-es státuszkódot ad vissza üres törzzsel.

GET /events/{eventId}

Egyetlen eseményt kér le azonosító alapján, ugyanazzal a struktúrával, mint a GET /events elemei.

GET /events/{eventId}/children

Felsorolja a szülőeseménybe ágyazott aleseményeket — egy nagyobb esemény tematikus sávjait vagy szekcióit. Minden alesemény felépítése megegyezik egy normál eseményével.

Résztvevők kezelése

Három végpont lehetővé teszi, hogy a Ludoyán kívülről kezeld egy esemény résztvevőlistáját — hasznos, ha a regisztrációk a saját weboldaladon történnek, vagy ha egy meglévő listát importálsz.

GET /members

Egy lapozott taglistát ad vissza.

Minden tagnál megtalálható: id, username, name, avatarUrl, role (OWNER, ADMIN vagy MEMBER).

POST /members/invite

Meghív valakit a csoportodba. Ez közvetlenül egy username-et fogad — nincs szükség ID-keresésre —, így a saját webhelyedről vagy adminisztrációs eszközödből egyenesen felvehetsz tagokat.

GET /search/users és GET /search/boardgames

A két keresési végpont. A legtöbb írási művelet név helyett azonosítót vár, és ezeken keresztül szerezhetsz egyet.

GET /search/users

GET /search/boardgames

A játékok szűrője ugyanazt a pontosvesszővel elválasztott key=value formátumot használja, mint a gyűjteményszűrő, így a katalógusban kereshetsz játékosszám, játékidő, összetettség, év, életkor vagy címkék szerint.

GET /collection

Visszaadja a játékgyűjteményedet szűréssel, rendezéssel és lapozással.

Válasz: totalGames, totalExpansions, games[] — mindegyik a következőkkel: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Egy konfigurálható időablakra vonatkozó játszma-statisztikákat ad vissza.

A válasz tartalmazza:

• Összefoglaló — összes játszma, összes/átlagos játékidő, egyedi játékok, játékosok és helyszínek száma
• Játékos szerint — játszmák személyenként, győzelmek, átlag- és legjobb pontszám
• Játékosszám szerint — 2 fős, 3 fős, 4 fős stb. játszmák bontása
• Helyszín szerint — játszmaszám és egyedi játékok helyszínenként
• Játék szerint — játszmaszám, összes/átlagos játékidő és egyedi játékosok játékonként

GET /campaigns

Visszaadja a csoporthoz tartozó kampányok lapozható listáját.

Minden kampány tartalmazza: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Visszaadja a csoporthoz tartozó kampány teljes részleteit.

A válasz tartalmazza: A lista összes mezőjét, továbbá template, description, globalNotes, globalState, members[] (mindegyiknél: user, role, characterNotes, characterState), sessions[] és events[].

POST /campaigns

Kampányt hoz létre a csoport számára. Kötelező mezők: gameId és name. A láthatóság alapértelmezetten csak csoporttagok számára (ONLY_GROUP), ha nincs megadva.

Opcionális mezők: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS vagy PRIVATE).

{"id": "string"}-t ad vissza 201-es státuszkóddal.

PUT /campaigns/{campaignId}

Frissít egy meglévő kampányt. Minden mező opcionális — csak azt add meg, amit módosítani szeretnél.

Opcionális mezők: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

202-es státuszkóddal tér vissza, üres törzzsel.

A kampány tagjai

Kezeld a kampány tagjait ugyanúgy, ahogyan az esemény résztvevőit.

Hibakódok

Első lépések

1. API-kulcs létrehozása

1. Lépj a szervezeted profiloldalára
2. Koppints a menüre (⋮) → Nyilvános API
3. Koppints a Kulcs létrehozása gombra
4. Azonnal másold ki a kulcsodat — csak egyszer jelenik meg, és később nem kérhető le újra

A kulcs a szervezetedhez van kötve. Tartsd titokban: akinél a kulcs van, az a fenti összes adatot olvashatja és írhatja.

2. Visszavonás vagy újbóli létrehozás

Egy meglévő kulcs visszavonásához menj vissza a Nyilvános API oldalra, és koppints a Visszavonás gombra. Erősítsd meg a megjelenő párbeszédablakot. Bármely rendszer, amely a régi kulcsot használja, azonnal 401-es hibákat fog kapni. Új kulcs létrehozásához koppints ismét a Kulcs létrehozása gombra.

Kapcsolódó:

• Szervezetek — szervezeti fiókok és prémium funkciók
• Prémium — a Business csomag árazása
• Integrációk — más módok a Ludoya összekapcsolására külső eszközökkel