Публично API

Публичното API дава на администраторите на организацията директен HTTP достъп до живите данни на вашата организация — издърпайте ги в който и да е сайт, приложение, бот или автоматизация, способна да направи HTTP заявка. Това е функция на плана Business.

Ключът е ограничен до вашата организация — всички крайни точки работят автоматично с тази група. Основен URL: https://api.ludoya.com/public/v1. Заглавка за удостоверяване: X-Api-Key: YOUR_KEY. Ограничение: 100 заявки в минута, след което получавате 429.

Ключовете започват с ldy_ и са дълги 36 знака, така че лесно се забелязват в конфигурационен файл — и лесно се търсят, ако някой попадне там, където не трябва. Отнасяйте се към него като към парола: само от страна на сървъра, и го оттеглете от същата страница, ако изтече.

До какво имате достъп

• Местоположения — наличните места на вашата група и техните позиции; използват се като вход при създаване на събития
• Събития (четене) — предстоящи и минали събития със заглавие, описание, дата и час, часова зона, капацитет, брой участници и статус
• Събития (запис) — създавайте и обновявайте събития чрез POST и PUT, с пълен контрол над мястото, капацитета, правата, видимостта и изображението
• Подсъбития — избройте събитията, вложени в родителско събитие
• Участници — добавете някого към събитие, променете присъствието му или го премахнете
• Членове — списък с членове с потребителски профили и роли (Собственик, Администратор, Член), страниран
• Покани — поканете някого в групата си
• Търсене — намирайте потребители на Ludoya и каталога с настолни игри, за да превърнете имена в ID преди запис
• Колекция — колекция от игри с филтриране по притежание, име, брой играчи и списък; сортируема и странирана; всяка игра включва метаданни от BGG
• Статистика — статистика на партиите за произволен период: суми, средни стойности, най-добри играчи с победи и резултати, разбивки по брой играчи, по местоположение и по игра
• Кампании (четене) — избройте кампаниите на групата с броя членове и сесии; вземете пълните детайли на кампания, включително членове, минали сесии и насрочени събития
• Кампании (запис) — създавайте кампании за групата и обновявайте името, описанието, статуса и видимостта им
• Членове на кампания — добавяйте, обновявайте и премахвайте хората в кампания

Крайни точки

GET /locations

Връща наличните местоположения на групата. Всяко местоположение има id, name, незадължителен address, capacity, флаг isDefault и масив spots (всяка позиция има собствени id, name и capacity). Използвайте ID на местоположения и позиции, когато създавате събития.

Влизане с Ludoya

Същата страница, на която стои API ключът ви, превръща организацията ви и в доставчик на вход. Позволете на хората да влизат в собствения ви сайт, форум или платформа на общността с акаунта си в Ludoya — без отделна парола, която да забравят, и без потребителска база данни, която вие да поддържате.

Защо си струва

Когато някой одобри входа, той се свързва с вашата организация: според правилата на групата ви за присъединяване или става член веднага (отворена), или подава заявка за присъединяване, която администратор одобрява (по заявка), или просто влиза, без да се присъединява (само с покана). Така или иначе той се появява в крайната точка /members като всеки друг — така входът в сайта ви и списъкът ви с членове в Ludoya остават автоматично в синхрон.

Настройка

Това е стандартен OpenID Connect, така че повечето платформи не се нуждаят от нищо друго освен issuer URL плюс client ID и secret. Регистрирайте приложението си от страницата Публично API, за да получите тези данни, и избройте redirect URI, които сайтът ви ще използва — можете да регистрирате няколко и всеки трябва да съвпада с redirect_uri, който сайтът ви изпраща, знак по знак, включително крайната наклонена черта. Почти-съвпадението е най-честата причина първият опит за вход да се провали.

• Discourse — инсталирайте приставката OpenID Connect, поставете discovery URL, добавете данните
• WordPress — всяка обща приставка за OpenID Connect, с нейната опция "auto discover"
• Всичко останало — ако говори OIDC, насочете го към issuer URL и то само се конфигурира

Всяко влизане връща постоянния идентификатор на човека, потребителското му име, показваното име и аватара, както и имейла му. Пълните инструкции за настройка, включително ръчния поток, са в ръководството за разработчици в приложението, под Developers → Sign in with Ludoya.

За хората, които влизат

Всеки, който е използвал Ludoya, за да влезе някъде, може да прегледа тези връзки в Настройки → Свързани приложения, да види кога всяка е била свързана и използвана за последно, и да прекъсне която и да е от тях по всяко време. Прекъсването отнема достъпа на сайта незабавно, но не го премахва от групата ви.

GET /events

Връща бъдещи и минали събития в отделни страницирани списъци.

Всяко събитие включва: type (MEETUP или PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (потребителски обект или null), master (потребителски обект или null). Потребителските обекти съдържат id, username, name, avatarUrl.

POST /events

Създава събитие в групата. Задължителни полета: type и title. Ако locationId е пропуснат, се използва местоположението по подразбиране на групата; ако няма такова, се връща 400.

Незадължителните полета включват: description, locationId, spotId, gameId, parentEventId (за подсъбития), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Полето image приема или {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Максимум 5 MB.

Връща {"id": "string"} със статус 201.

PUT /events/{eventId}

Актуализира съществуващо събитие. Същата структура на тялото като при POST — включете само полетата, които искате да промените. Извикващият трябва да е организаторът на събитието (груповият профил). Връща 202 с празно тяло.

GET /events/{eventId}

Извлича едно събитие по id със същата структура като записите в GET /events.

GET /events/{eventId}/children

Извежда подсъбитията, вложени в основно събитие — отделните направления или сесии на по-голямо мероприятие. Всяко подсъбитие има същата структура като обикновено събитие.

Управление на участниците

Три крайни точки ви позволяват да управлявате списъка с участници в събитие извън Ludoya — удобно, ако записванията стават на собствения ви сайт или ако внасяте съществуващ списък.

GET /members

Връща страниран списък с членове.

Всеки член включва: id, username, name, avatarUrl, role (OWNER, ADMIN, или MEMBER).

POST /members/invite

Поканва някого в групата ви. Този приема директно username – не е нужно търсене по id – така че можете да добавяте членове направо от собствения си сайт или административен инструмент.

GET /search/users and GET /search/boardgames

Двете крайни точки за търсене. Повечето операции за запис искат id, а не име, и ето откъде се взема.

GET /search/users

GET /search/boardgames

Филтърът за настолни игри приема същата форма key=value, разделена с точка и запетая, както филтърът за колекцията, така че можете да търсите в каталога по брой играчи, време на игра, сложност, година, възраст или етикети.

GET /collection

Връща вашата колекция от игри с филтриране, сортиране и странициране.

Отговор: totalGames, totalExpansions, games[] — всяка с: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Връща статистика за партиите за настройваем времеви прозорец.

Отговорът включва:

• Обобщение — общ брой партии, общо/средно време на игра, брой уникални игри, играчи и местоположения
• По играч — партии, победи, среден и най-добър резултат за всеки човек
• По брой играчи — разбивка на игри за 2, 3, 4 играчи и т.н.
• По местоположение — брой партии и уникални игри за всяко място
• По игра — брой партии, общо/средно време на игра и уникални играчи за всяко заглавие

GET /campaigns

Връща страниран списък с кампании, принадлежащи на групата.

Всяка кампания включва: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Връща пълните детайли на кампания, принадлежаща на групата.

Отговорът включва: Всички полета от списъка, плюс template, description, globalNotes, globalState, members[] (всеки с user, role, characterNotes, characterState), sessions[] и events[].

POST /campaigns

Създава кампания за групата. Задължителни полета: gameId и name. Ако видимостта е пропусната, по подразбиране е само за членове на групата (ONLY_GROUP).

Незадължителни полета: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS или PRIVATE).

Връща {"id": "string"} със статус 201.

PUT /campaigns/{campaignId}

Актуализира съществуваща кампания. Всички полета са незадължителни — включете само това, което искате да промените.

Незадължителни полета: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Връща 202 с празно тяло.

Членове на кампанията

Управлявайте кой участва в кампания по същия начин, по който управлявате участниците в събитие.

Кодове за грешка

Първи стъпки

1. Генериране на API ключ

1. Отидете на профилната страница на вашата организация
2. Докоснете менюто (⋮) → Публично API
3. Докоснете Генерирай ключ
4. Копирайте ключа си незабавно — показва се само веднъж и не може да бъде извлечен отново

Ключът е обвързан с вашата организация. Пазете го в тайна: всеки, който разполага с него, може да чете и записва всички посочени по-горе данни.

2. Оттегляне или ново генериране

За да оттеглите съществуващ ключ, върнете се на страницата Публично API и докоснете Оттегли. Потвърдете диалоговия прозорец. Всяка система, използваща стария ключ, веднага започва да получава грешки 401. За да издадете нов ключ, докоснете отново Генерирай ключ.

Вижте също:

• Организации — акаунти за организации и премиум функции
• Premium — ценообразуване за Business плана
• Интеграции — други начини за свързване на Ludoya с външни инструменти