Partner API ФСБР — краткое руководство для партнёров

REST-справочник по клубам, игрокам, турнирам и столам платформы. Дополняет поток событий GSS (live-события за столами): оба сервиса работают по одному и тому же ключу партнёра, одному набору прав и одному списку клубов.

Параметр Production Stage (тест)
Base URL https://partner-api.fsbr-app.ru/partner/v1 https://partner-api.fsbr-app-stage.ru/partner/v1
Интерактивная спецификация (OpenAPI) https://partner-api.fsbr-app.ru/docs https://partner-api.fsbr-app-stage.ru/docs
Ключ bgm_live_… bgm_test_…

Только чтение, только GET, только HTTPS.

Аутентификация

Каждый запрос несёт заголовок X-Partner-Key: <ключ> — ключ целиком, вместе с префиксом. Ключ выдаёт федерация один раз при подключении; восстановить его нельзя, при утере — перевыпуск (старый ключ перестаёт работать сразу, без переходного периода). Срока действия у ключа нет.

Проверить ключ: GET /me — вернёт имя партнёра, выданные права и список клубов.

curl -H "X-Partner-Key: bgm_live_…" https://partner-api.fsbr-app.ru/partner/v1/me

Права (scopes) и клубы

Ключу выдаётся набор прав; каждая группа эндпоинтов требует одно из них:

Право Открывает
clubs:read /clubs
players:read /players
tournaments:read /tournaments
matches:read /matches
events:read поток GSS (не REST)

Кроме прав, ключ может быть ограничен списком клубов: всё, что не относится к этим клубам, для партнёра не существует — не попадает в списки, а прямой запрос по id отвечает 404, а не 403. Без ограничения партнёр видит все клубы федерации.

Ответы

HTTP code Значение
401 PARTNER_KEY_REQUIRED заголовок не передан
401 PARTNER_KEY_INVALID ключ неизвестен (опечатка, старый ключ после перевыпуска)
401 PARTNER_INACTIVE ключ верный, но партнёр отключён — обратитесь в федерацию
403 PERMISSION_DENIED у ключа нет нужного права
404 CLUB_NOT_FOUND / USER_NOT_FOUND / TOURNAMENT_NOT_FOUND / MATCH_NOT_FOUND объекта нет или он вне ваших клубов
404 NOT_FOUND GET /tournaments/{id}/rounds/{n}/standings для тура, который ещё не сыгран
422 VALIDATION_ERROR неверные параметры (см. ограничения ниже)

Эндпоинты

Клубы — clubs:read

Эндпоинт Что отдаёт
GET /clubs Каталог активных клубов (в пределах вашего списка), по имени. Клуб, который владелец скрыл из каталога, сюда не попадает, но по GET /clubs/{club_id} отдаётся.
GET /clubs/{club_id} Карточка: id, short_id, name, description, logo_url, contacts, member_count.

Игроки — players:read

Только публичный профиль: id, short_id, display_name, avatar_url, rating, is_bot. Персональных данных (ФИО, контакты, документы) API не отдаёт. Игроки с закрытым профилем, удалённые и неактивные → 404.

Эндпоинт Что отдаёт
GET /players?ids=…&ids=… Пакетный запрос, до 100 id за раз. Недоступные id молча пропускаются, порядок запроса сохраняется.
GET /players/{user_id} Профиль.
GET /players/{user_id}/tournaments История турниров игрока (в ваших клубах): пара, партнёр, место, результат. Новые сверху.

Турниры — tournaments:read

Статусы: registration → active → finished (→ archived), а также cancelled, did_not_take_place. Черновики никогда не отдаются.

Эндпоинт Что отдаёт
GET /tournaments Список. Фильтры: club_id (повторяемый), status (повторяемый), starts_from / starts_to (окно ≤ 31 день, если заданы оба), streamable (true/false). Сортировка по starts_at.
GET /tournaments/upcoming?n_days=N Расписание: идущие сейчас и открытые к регистрации турниры со стартом в ближайшие N дней (1–7). Удобно для поллинга.
GET /tournaments/{id} Карточка: формат, подсчёт (scoring_method), boards_per_round, rounds_count, starts_at, registration_deadline, prize_pool, клуб, серия, streamable.
GET /tournaments/{id}/rounds Туры: номер, статус (scheduled / active / correction / finished), время, число столов.
GET /tournaments/{id}/pairs Пары: два игрока (публичный профиль), display_name, withdrawn_at.
GET /tournaments/{id}/standings Турнирная таблица (страницами).
GET /tournaments/{id}/rounds/{n}/standings Таблица на конец тура n.

Призовой фонд турнира — это prize_pool (Money): суммарная выплата по призовой таблице, та цифра, которую показывают игрокам. Соседний prize_fund — не фонд, а база на одного игрока, от которой считаются процентные призы; показывать её как фонд нельзя.

streamable — признак того, что столы турнира могут транслироваться партнёрам через GSS. Это поле и фильтр, не ограничение доступа к справочным данным.

Столы / матчи — matches:read

Стол = один матч одной пары NS против одной пары EW в одном туре. Тренировочные столы вне турниров не отдаются.

Статусы: SCHEDULED (создан, игра не началась) → WAITING → ACTIVE → FINISHED; также PAUSED, CANCELLED и ANNULLED — судья перезапустил стол с первой сдачи под новым id (прежняя попытка не засчитывается; в списки столов и tables_count такие столы не попадают, по id отдаются). Столы тура появляются в момент открытия тура — расписание на будущие туры заранее не существует, поллите SCHEDULED/WAITING.

Эндпоинт Что отдаёт
GET /matches Список. Фильтры: tournament_id, club_id (повторяемый), status (повторяемый), created_from / created_to. Новые сверху.
GET /matches/{match_id} Карточка: tournament_id, round_number, table_number, status, format, ns_pair / ew_pair с игроками, boards_planned, started_at / finished_at, winner_side, results по сторонам (mp_total / imp_total / is_winner).

Идентификатор стола (id) — тот же, что tableId в событиях GSS: по нему события потока сопоставляются со справочными данными.

Рекомендации по интеграции

Вопросы и перевыпуск ключа — через контактное лицо федерации.