Veřejné API

Veřejné API dává administrátorům organizace přímý HTTP přístup k živým datům vaší organizace — natáhněte je do jakéhokoli webu, aplikace, bota či automatizace, která umí poslat HTTP požadavek. Je to funkce tarifu Business.

Klíč je vázán na vaši organizaci — všechny endpointy pracují automaticky s touto skupinou. Základní URL: https://api.ludoya.com/public/v1. Autentizační hlavička: X-Api-Key: YOUR_KEY. Limit: 100 požadavků za minutu, poté dostanete 429.

Klíče začínají na ldy_ a mají 36 znaků, takže je snadno poznáte v konfiguračním souboru — a snadno se po nich dá pátrat, kdyby některý skončil tam, kde nemá. Zacházejte s ním jako s heslem: jen na serveru, a při úniku ho ze stejné stránky zneplatněte.

K čemu se dostanete

• Lokality — dostupné prostory vaší skupiny a jejich místa; slouží jako vstup při vytváření akcí
• Akce (čtení) — nadcházející i minulé akce s názvem, popisem, datem a časem, časovou zónou, kapacitou, počtem účastníků a stavem
• Akce (zápis) — vytvářejte a upravujte akce přes POST a PUT, s plnou kontrolou nad místem, kapacitou, oprávněními, viditelností a obrázkem
• Podakce — vypište akce vnořené uvnitř nadřazené akce
• Účastníci — přidejte někoho na akci, změňte jeho účast nebo ho odeberte
• Členové — seznam členů s profily a rolemi (Vlastník, Administrátor, Člen), stránkovaný
• Pozvánky — pozvěte někoho do své skupiny
• Hledání — vyhledejte uživatele Ludoyi i katalog deskových her, abyste před zápisem převedli jména na ID
• Sbírka — herní sbírka s filtrováním podle vlastnictví, názvu, počtu hráčů a seznamu; řaditelná a stránkovaná; každá hra obsahuje metadata z BGG
• Statistiky — statistiky partií za libovolné období: souhrny, průměry, nejlepší hráči s výhrami a skóre, rozpady podle počtu hráčů, podle lokality a podle hry
• Kampaně (čtení) — vypište kampaně skupiny s počty členů a sezení; načtěte úplné podrobnosti kampaně včetně členů, minulých sezení a naplánovaných akcí
• Kampaně (zápis) — vytvářejte kampaně pro skupinu a upravujte jejich název, popis, stav a viditelnost
• Členové kampaně — přidávejte, upravujte a odebírejte lidi v kampani

Endpointy

GET /locations

Vrací dostupné lokality skupiny. Každá lokalita má id, name, volitelnou address, capacity, příznak isDefault a pole spots (každé místo má vlastní id, name a capacity). Při vytváření akcí používejte ID lokalit a míst.

Přihlášení přes Ludoyu

Tatáž stránka, kde máte API klíč, promění vaši organizaci i ve poskytovatele přihlášení. Nechte lidi přihlašovat se na váš web, fórum nebo komunitní platformu jejich účtem na Ludoyi — žádné další heslo, které by mohli zapomenout, a žádná databáze uživatelů, kterou byste museli provozovat.

Proč to stojí za to

Když někdo přihlášení schválí, propojí se s vaší organizací: podle pravidel vaší skupiny pro přijetí se buď rovnou stane členem (otevřená), podá žádost o členství, kterou schválí administrátor (na žádost), nebo se prostě přihlásí, aniž by vstoupil (jen na pozvání). Tak či tak se objeví v endpointu /members jako kdokoli jiný — takže přihlašování na vašem webu a váš seznam členů na Ludoyi zůstávají automaticky v souladu.

Nastavení

Jde o standardní OpenID Connect, takže většina platforem nepotřebuje nic než issuer URL plus client ID a secret. Registrujte svou aplikaci ze stránky Veřejné API, abyste tyto údaje získali, a vypište redirect URI, které váš web použije — můžete jich zaregistrovat několik a každá musí odpovídat redirect_uri, které váš web posílá, znak po znaku, včetně koncového lomítka. Těsný nesoulad je zdaleka nejčastější důvod, proč první pokus o přihlášení selže.

• Discourse — nainstalujte plugin OpenID Connect, vložte discovery URL, doplňte údaje
• WordPress — jakýkoli obecný plugin pro OpenID Connect a jeho volba "auto discover"
• Cokoli dalšího — pokud to mluví OIDC, nasměrujte to na issuer URL a nastaví se samo

Každé přihlášení vrátí trvalý identifikátor dané osoby, její uživatelské jméno, zobrazované jméno a avatar a její e-mail. Úplné pokyny k nastavení, včetně ručního průběhu, najdete v průvodci pro vývojáře v aplikaci pod Developers → Sign in with Ludoya.

Pro ty, kdo se přihlašují

Kdokoli, kdo se někam přihlásil přes Ludoyu, si tato propojení může prohlédnout v Nastavení → Připojené aplikace, vidět, kdy bylo které připojeno a naposledy použito, a kterékoli z nich kdykoli odpojit. Odpojení okamžitě odřízne webu přístup, ale z vaší skupiny je neodstraní.

GET /events

Vrací budoucí a minulé akce ve dvou samostatných stránkovaných seznamech.

Každá akce obsahuje: type (MEETUP nebo PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objekt uživatele nebo null), master (objekt uživatele nebo null). Objekty uživatele obsahují id, username, name, avatarUrl.

POST /events

Vytvoří akci ve skupině. Povinná pole: type a title. Pokud locationId vynecháte, použije se výchozí lokalita skupiny; pokud žádná není, vrátí se 400.

Volitelná pole zahrnují: description, locationId, spotId, gameId, parentEventId (pro podakce), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Pole image přijímá buď {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Maximálně 5 MB.

Vrací {"id": "string"} se stavem 201.

PUT /events/{eventId}

Aktualizuje existující akci. Stejná struktura těla jako u POST — uveďte pouze pole, která chcete změnit. Volající musí být pořadatelem akce (skupinový účet). Vrací 202 s prázdným tělem.

GET /events/{eventId}

Načte jednu událost podle id se stejnou strukturou jako položky v GET /events.

GET /events/{eventId}/children

Vypíše podakce vnořené uvnitř nadřazené akce — jednotlivé programové linie nebo sezení většího setkání. Každá podakce má stejnou strukturu jako běžná akce.

Správa účastníků

Tři endpointy vám umožní řídit seznam účastníků akce zvenčí Ludoyi — hodí se, když se přihlašuje přes váš vlastní web nebo když importujete existující seznam.

GET /members

Vrací stránkovaný seznam členů.

Každý člen obsahuje: id, username, name, avatarUrl, role (OWNER, ADMIN, nebo MEMBER).

POST /members/invite

Pozve někoho do vaší skupiny. Tento endpoint přijímá přímo username – není potřeba vyhledávat id – takže můžete přidávat členy rovnou z vlastního webu nebo administračního nástroje.

GET /search/users and GET /search/boardgames

Dva vyhledávací endpointy. Většina zápisových operací chce místo názvu id, a takhle ho získáte.

GET /search/users

GET /search/boardgames

Filtr deskových her přijímá stejný tvar key=value oddělený středníkem jako filtr sbírky, takže katalog můžete prohledávat podle počtu hráčů, herního času, složitosti, roku, věku nebo štítků.

GET /collection

Vrací vaši herní sbírku s filtrováním, řazením a stránkováním.

Odpověď: totalGames, totalExpansions, games[] — každá s: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Vrací statistiky partií za nastavitelné časové okno.

Odpověď obsahuje:

• Souhrn — celkový počet partií, celkový/průměrný herní čas, počty unikátních her, hráčů a lokalit
• Podle hráče — partie, výhry, průměrné a nejlepší skóre na osobu
• Podle počtu hráčů — rozdělení na hry pro 2, 3, 4 hráče atd.
• Podle lokality — počet partií a unikátních her na místo
• Podle hry — počet partií, celkový/průměrný herní čas a unikátní hráči na titul

GET /campaigns

Vrací stránkovaný seznam kampaní patřících skupině.

Každá kampaň obsahuje: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Vrací úplné podrobnosti kampaně patřící skupině.

Odpověď obsahuje: Všechna pole ze seznamu, plus template, description, globalNotes, globalState, members[] (každý s user, role, characterNotes, characterState), sessions[] a events[].

POST /campaigns

Vytvoří kampaň pro skupinu. Povinná pole: gameId a name. Pokud viditelnost vynecháte, je výchozí pouze pro členy skupiny (ONLY_GROUP).

Volitelná pole: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS nebo PRIVATE).

Vrací {"id": "string"} se stavem 201.

PUT /campaigns/{campaignId}

Aktualizuje existující kampaň. Všechna pole jsou volitelná — uveďte pouze to, co chcete změnit.

Volitelná pole: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Vrací 202 s prázdným tělem.

Členové kampaně

Spravujte, kdo je v kampani, stejně jako spravujete účastníky akce.

Chybové kódy

Začínáme

1. Vygenerujte API klíč

1. Přejděte na stránku profilu své organizace
2. Klepněte na nabídku (⋮) → Veřejné API
3. Klepněte na Vygenerovat klíč
4. Klíč si ihned zkopírujte — zobrazí se pouze jednou a znovu jej nelze získat

Klíč je vázán na vaši organizaci. Uchovejte jej v tajnosti: kdokoli s tímto klíčem může číst i zapisovat všechna výše uvedená data.

2. Zneplatnění nebo nové vygenerování

Chcete-li zneplatnit existující klíč, vraťte se na stránku Veřejné API a klepněte na Zneplatnit. Potvrďte dialog. Každý systém používající starý klíč začne okamžitě dostávat chyby 401. Nový klíč vydáte opětovným klepnutím na Vygenerovat klíč.

Související:

• Organizace — účty organizací a prémiové funkce
• Premium — ceny plánu Business
• Integrace — další způsoby, jak propojit Ludoya s externími nástroji