Коины
Начисление и списание коинов одному игроку или массово по всему серверу.
Изменение баланса коинов: одному игроку (POST /v1/players/{ref}/coins) или всем
(POST /v1/economy/coins). Каждая операция попадает в журнал экономики с указанной причиной
reason — прочитать его можно через
GET /v1/economy/transactions.
Знаковая величина
amount — знаковая дельта: положительное значение начисляет, отрицательное списывает.
0 отклоняется (400). Панель по знаку выбирает нужную операцию на игровом сервере и всегда шлёт
модуль значения — отдельных эндпоинтов «начислить»/«списать» нет. В ответе amount возвращается со
знаком, как вы прислали.
Операции с коинами НЕ идемпотентны — шлите Idempotency-Key
В отличие от бана/мьюта, изменение коинов — это дельта: применённая дважды, она удваивается.
Повтор при сетевом сбое может задвоить. Шлите Idempotency-Key, чтобы
повтор воспроизвёл первый результат, а не добавил ещё раз.
POST /v1/players/{ref}/coins
Изменить баланс одного игрока. {ref} — Steam64 или Discord-идентификатор с префиксом
(discord:123456789012345678); discord:-реф резолвится в привязанного игрока.
Скоуп: economy:write.
| Поле | Тип | Значение |
|---|---|---|
amount | целое ≠ 0 | Знаковая дельта. Плюс начисляет, минус списывает. |
reason | строка (1–500) | Обязательно — попадает в запись журнала. |
POST /v1/players/76561198000000000/coins
Content-Type: application/json
{ "amount": 500, "reason": "event reward" }Возвращает новый баланс и личность игрока (Discord рядом со Steam — discord_id = null, если игрок
не привязан):
{ "amount": 500, "balance": 1500, "player": { "steam_id": "76561198000000000", "discord_id": "123456789012345678" } }Начисление неизвестному Steam id создаёт игрока
Положительное начисление на корректный Steam64, которого ещё не было на сервере, создаёт
запись игрока и начисляет (200) — как и штатно на игровом сервере. Отрицательное изменение
неизвестному игроку возвращает 404 not_found. Списание больше баланса — 409 conflict.
POST /v1/economy/coins
Изменить баланс сразу многим игрокам.
Скоуп: economy:write_all (отдельный, более мощный скоуп, чем одиночный — ключ, который пополняет
отдельных игроков, не сможет обнулить всю экономику).
| Поле | Тип | Значение |
|---|---|---|
amount | целое ≠ 0 | Знаковая дельта для каждого затронутого игрока. |
reason | строка (1–500) | Обязательно — попадает в запись журнала. |
target | all | online | Кого затронуть. По умолчанию all. |
all(по умолчанию) — все игроки на сервере, онлайн и офлайн (включая давно ушедших). Это «большой молоток»; по умолчанию так только потому, что это совпадает с текущим поведением игрового сервера «выдать всем».online— только игроки сейчас в онлайне.
`target: online` требует свежего игрового сервера
Онлайн-таргет обслуживается отдельным роутом игрового сервера. Если подключённый сервер старее, вызов
вернёт 404 not_found с сообщением об обновлении — он никогда не применяется молча ко всем.
Обновите игровой сервер или используйте target: all.
POST /v1/economy/coins
Content-Type: application/json
{ "amount": 100, "reason": "server anniversary", "target": "online" }{ "amount": 100, "affected_count": 7, "target": "online" }Массовые операции ограничены по частоте
Массовые операции имеют общий кулдаун 5 секунд на игровом сервере. Второй массовый вызов внутри
окна вернёт 429 rate_limited с заголовком Retry-After.
Ошибки
Стандартный конверт ошибок.
| Код | Статус | Когда |
|---|---|---|
insufficient_scope | 403 | У ключа нет economy:write (одиночный) или economy:write_all (массовый). |
not_found | 404 | Нет игрока по {ref} (непривязанный Discord id); списание у неизвестного игрока; или target: online на слишком старом игровом сервере. |
conflict | 409 | Списание превышает баланс игрока (сообщение сервера — в error.message). |
validation_error | 400 | amount равен 0/отсутствует, нет reason, неизвестный target или отказ игрового сервера (его сообщение — в error.details.mod_message). |
rate_limited | 429 | Кулдаун массовых операций 5 секунд (см. выше). |
server_unavailable | 503 | Игровой сервер офлайн или недоступен. |
gateway_timeout | 504 | Сервер не ответил вовремя. |