Публичный API

«Публичный API» предоставляет администраторам организации прямой HTTP‑доступ к актуальным данным вашей организации — подключайте их к любому веб‑сайту, приложению, боту или автоматизации, которые могут отправлять HTTP‑запросы. Это функция Бизнес‑плана.

Ключ привязан к вашей организации — все конечные точки работают с этой группой автоматически. Базовый 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 — без отдельного пароля, который можно забыть, и без пользовательской базы данных, которую вам пришлось бы обслуживать.

Почему это стоит того

Когда пользователь одобряет вход, он связывается с вашей организацией: в зависимости от политики вступления вашей группы он либо сразу становится участником (открытая), либо подаёт запрос на вступление для одобрения администратором (запрос на вступление), либо просто входит, не присоединяясь (только по приглашениям). В любом случае он появляется в endpoint /members, как и любой другой — поэтому вход на вашем сайте и ваш список участников в Ludoya остаются синхронизированными автоматически.

Настройка

Это стандартный OpenID Connect, поэтому большинству платформ нужны лишь URL издателя плюс ID клиента и секрет. Зарегистрируйте своё приложение на странице Public API, чтобы получить эти учётные данные, и перечислите URI перенаправления, которые будет использовать ваш сайт — можно зарегистрировать несколько, и каждый должен совпадать с отправляемым вашим сайтом redirect_uri символ в символ, включая завершающую косую черту. Небольшое несовпадение — самая частая причина неудачи при первой попытке входа.

• Discourse — установите плагин OpenID Connect, вставьте URL обнаружения, добавьте учётные данные
• WordPress — любой универсальный плагин OpenID Connect, с опцией "auto discover"
• Любая другая платформа — если она поддерживает OIDC, укажите ей URL издателя, и она настроится сама

Каждый вход возвращает постоянный идентификатор человека, его имя пользователя, отображаемое имя и аватар, а также адрес электронной почты. Полные инструкции по настройке, включая ручной сценарий, доступны в руководстве для разработчиков внутри приложения: Разработчики → Вход с помощью 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 и 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 к внешним инструментам