Результаты клуба → MafiaSpace

Адрес и доступ

Базовый адрес: https://mafiaspace.ru

Ключ выдаёт команда MafiaSpace отдельно. Заголовок каждого запроса: Authorization: Bearer <ключ>. Для тела — Content-Type: application/json. Ключ храните только на сервере, без браузера, мобильного клиента и логов.

Есть два отдельных ключа: sandbox и production. Адрес API одинаковый; среду определяет ключ. Тестовые игры не создают публичных игроков и не влияют на настоящий рейтинг. Проверить клуб и среду: GET /v1/integrations/game-results/me. Не отправляйте вымышленные примеры рабочим ключом.

Ключ закреплён за конкретным клубом: поле clubId в игре отсутствует, менять клуб через запрос нельзя. me возвращает acceptGamesFrom — начало разрешённого периода новых игр. Более старые игры отклоняются для защиты от повторной загрузки архива.

Быстрый старт

1. Получите тестовый ключ, проверьте me: environment должен быть sandbox.
2. Скачайте example-game.json и game.schema.json.
3. Отправьте пример командой ниже. Первый ответ — 201, повтор — 200.
4. Посмотрите тестовую таблицу через GET /v1/integrations/game-results/standings.
5. Проверьте исправление и отмену. Затем используйте рабочий ключ для настоящих игр.

curl --fail-with-body --request PUT \
  'https://mafiaspace.ru/v1/integrations/game-results/example-game-001' \
  --header "Authorization: Bearer $MAFIASPACE_SANDBOX_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @example-game.json

Методы

validate принимает { "externalGameId": "example-game-001", "game": <JSON игры> }. Успех: { "valid": true, "effect": "write", "warnings": [], "game": {...}, "requestId": "..." }. Для точного повтора effect равен repeat. Проверка не резервирует версию.

Обязательные данные игры

Допустимы необязательные externalEventId (ID вечера) и eventTitle (название, 1–200 символов). Они сохраняют контекст результата; календарная запись не создаётся автоматически. Ночные действия, голосования и полный протокол не требуются. Статистика таких действий из итогового результата не выводится.

ID игры в URL и ID игрока/вечера: 1–100 символов [A-Za-z0-9._-]. Для ID игры запрещены me, validate, standings. ID не меняется вместе с ником, датой или названием вечера и не переиспользуется для другой игры/человека. Если своих ID нет, создайте их один раз и сохраните в своей базе.

Баллы — строки с точкой, без знака минус, от 0 до 1000, максимум два знака после точки. Все три компонента обязательны. null, неизвестный итог, неполный состав, незнакомые поля и произвольный base отклоняются. При ничьей все три компонента равны нулю — это правило действующего рейтинга MafiaSpace. bonus должен уже включать все положительные начисления; не отправляйте туда общий итог. Штраф не вычитайте из bonus: передавайте отдельно в penalty.

Как игра попадает в рейтинг

Сервер проверяет победителя и базовые баллы, затем считает:

• Баллы за игру = base + bonus − penalty.
• Рейтинг = сумма баллов × число побед ÷ число игр.
• Место в основной таблице присваивается после 10 игр; до этого игрок виден в квалификации. Победы определяются по роли и победившей команде.

Рабочий запрос создаёт обычную завершённую игру и проекцию статистики. В рейтинге учитываются принятые по API игры вместе с остальными подходящими играми клуба. Полный протокол при этом не выдумывается: источник помечен club_result_api. Частные зачёты с отдельными регламентами и номинациями по ночным событиям не назначаются автоматически; этот API пополняет текущий публичный рейтинг.

Одинаковый ник не объединяет людей. Постоянный externalPlayerId получает постоянную карточку игрока MafiaSpace. Уже существующие игровые профили можно связать через обычный механизм объединения профилей; аккаунт и права доступа от отправки результата не появляются. Не создавайте новый ID при смене ника.

Ссылка на полный рейтинг конкретного клуба приходит в me и в ответе рабочего сохранения как ratingUrl. Проверочная таблица standings относится только к вашему источнику, поэтому может отличаться от полной клубной таблицы, где есть другие игры и связанные профили.

Ответ на сохранение

Первая запись — 201. Исправление и точный повтор — 200. Пример ответа:

{
  "externalGameId": "example-game-001",
  "resultId": "<UUID приёма>",
  "gameId": "<UUID игры, только для production>",
  "revision": 1,
  "status": "saved",
  "environment": "production",
  "statistics": "updated",
  "visibility": "public",
  "ratingUrl": "https://mafiaspace.ru/clubs/56a5df76-0f19-482b-98a7-563953b0b0e1/ratings",
  "game": { "...": "полная нормализованная игра" },
  "voidReason": null,
  "requestId": "<ID запроса>"
}

В sandbox: gameId и ratingUrl равны null, statistics = sandbox_only, visibility = private. Проверяйте environment в ответах. updated подтверждает сохранение и обновление серверной проекции рейтинга в одной транзакции. Сайт и приложение получают результат при следующем обновлении данных; уже открытый или офлайн-экран сам по себе не подтверждает свежесть. Кэш рейтинга на обслуживающем сервере сбрасывается после записи; соседний сервер может держать данные до 45 секунд. Для разбора ошибки сохраните requestId. Годовой фильтр действующего рейтинга использует UTC; передавайте реальное время с правильным смещением часового пояса.

Повтор, исправление, отмена

Сохраняйте исходящие запросы в очереди на своём сервере. При тайм-ауте, сетевой ошибке или 5xx повторяйте тот же ID, revision и JSON: через 2, 5, 15, 60 секунд, затем раз в 5 минут с небольшим случайным разбросом. Не повышайте версию ради повтора. Удаляйте запрос из очереди после 200/201 с ожидаемой версией либо подтверждающего GET.

• Точная повторная отправка не меняет число игр или баллы. Порядок JSON-ключей и мест в массиве, эквивалентные часовые пояса и запись "0.3"/"0.30" нормализуются.
• Для исправления получите GET, увеличьте revision на один и передайте полную исправленную игру через PUT. Старый вклад заменится новым, включая смену даты.
• Одинаковая версия с разными данными и запоздавшая старая версия дают 409.
• Отмена: POST /v1/integrations/game-results/example-game-001/void с { "revision": 2, "reason": "Внесено по ошибке" }. Если игра уже имеет версию 2, отмена должна иметь версию 3. reason — 1–500 символов.
• Отмена убирает игру из рейтинга и сохраняет историю. Точный повтор отмены — 200. GET возвращает status: voided. Восстановление — через поддержку; новый ID для обхода отмены не создавайте. Игра из интеграции редактируется только этим API.

Лимиты: тело до 64 KiB, 60 запросов в минуту на источник, до 2 одновременно на обслуживающем сервере. При 429 соблюдайте заголовок Retry-After.

Ошибки

Формат: {"error":{"code":"invalid_game","message":"invalid_game","fields":[]},"requestId":"..."}. fields при ошибке поля содержит path и code. Ответ прокси при 5xx может быть не JSON.

Проверка перед запуском

В sandbox: проверка без записи → первая игра → повтор → исправление баллов → смена ника с прежним ID → отмена. Количество игр в проверочной таблице: 0 → 1 → 1 → 1 → 1 → 0. Убедитесь, что очередь переживает перезапуск вашего сервера.

Перед первой рабочей отправкой проверьте me, дату приёма и отсутствие этих же игр в уже загруженном архиве/других источниках. Один и тот же externalGameId предотвращает повтор внутри источника; другой ID или другой источник — другая запись, поэтому не отправляйте одну игру по двум каналам без сопоставления.

Ключи и поддержку предоставляет MafiaSpace. Передавать внутренний формат клубной системы не требуется: реализация ведётся по этой спецификации.