Публичный API
Через /public/v1 ваш код работает с теми же данными, что вы видите в кабинете: учётками, заданиями, дропами, матчами и слотами.
Адрес: https://split-team.com/public/v1
Фарм запускается заданиями (/tasks). Через POST /jobs ставится только забор дропа (cs2_claim_drop).
Ключ доступа
Передавайте ключ в заголовке Authorization: Bearer sft_… в каждом запросе.
Ключ выпускается в кабинете, в разделе «API».
GET /public/v1/whoami отвечает на любой действующий ключ, даже без скоупов, и возвращает название ключа, его начало, скоупы и срок действия.
Скоупы
Ключ выпускается с одним или несколькими скоупами. Операция, для которой скоупа не хватает, отвечает 403 insufficient_scope со списком недостающих скоупов в поле error.missing.
| Скоуп | Что даёт |
|---|---|
account:read | Аккаунт: чтениеВидеть слоты, подписки и неделю дропа. |
bots:read | Учётки: чтениеВидеть учётки, их дропы, матчи и прогоны. |
bots:write | Учётки: изменениеМенять метку и группы учёток, удалять их, отменять прогоны и ставить ручной забор дропа. |
bots:credentials | Учётки: паролиДобавлять учётки и менять их пароль и shared secret. Прочитать пароль этим ключом нельзя. |
tasks:read | Задания: чтениеВидеть задания и их состав. |
tasks:write | Задания: изменениеСоздавать и менять задания. |
Пагинация
Списки отдаются страницами. Параметры: limit от 1 до 200 (по умолчанию 50) и cursor со значением next_cursor из предыдущей страницы. В ответе поля items и next_cursor; на последней странице next_cursor нет.
У дропов, предложений дропа и матчей учётки доступны только последние записи. Сколько их, указано у операции в справочнике ниже.
Idempotency-Key
POST /bots, /bots/batch, /tasks и /jobs принимают заголовок Idempotency-Key: от 1 до 255 печатных символов ASCII. Ключ хранится 24 часа. Повтор с тем же ключом и телом вернёт ответ первой попытки с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом получит 422 idempotency_key_reused, а повтор, пока первый запрос ещё выполняется, получит 409 idempotency_in_progress.
Для пачек отправляйте его всегда: без него повтор после обрыва сети получит отказ «уже добавлена» на учётки, которые успел добавить первый запрос.
Открытые перечисления
Состояния учётки, причины остановки прогона, типы событий и коды отказа могут пополняться без смены версии /public/v1. Незнакомое значение показывайте как неизвестное и не считайте ошибкой.
Лимит частоты
Все ваши ключи вместе могут делать 10 запросов в секунду, всплеск до 30. POST /bots/batch ограничен отдельно: 1 запрос в 5 секунд. Заголовки RateLimit-Limit и RateLimit-Remaining приходят в каждом ответе на запрос, который прошёл проверку ключа и скоупа. При превышении приходит 429 rate_limited с заголовками RateLimit-Reset и Retry-After (сколько секунд подождать). Отдельно считаются все запросы с одного IP-адреса (для IPv6 с одной сети /64), в том числе отклонённые из-за ключа или скоупа: 60 в секунду, всплеск до 120. Клиент одного пользователя, который соблюдает лимит ключей, до этого порога не доходит; если с одного адреса работают ключи нескольких пользователей, лимит адреса у них общий. Превышение даёт тот же 429 rate_limited с Retry-After, но без заголовков RateLimit-*.
Значения могут измениться.
Коды отказа
Ошибка приходит объектом error с полями code и message, а при нехватке скоупа ещё и missing. Рядом с ним лежит request_id, тот же, что в заголовке X-Request-Id. Список кодов может пополняться, ниже те, что есть сейчас.
invalid_api_keyinsufficient_scoperate_limitedinternalbad_idempotency_keyidempotency_key_reusedidempotency_in_progressnot_foundbad_limitbad_cursorbad_requestmethod_not_allowedjob_type_not_allowedbad_game_idbad_labelbad_steam_usernamebad_steam_passwordbad_steam_shared_secretbad_steam_identity_secretduplicate_steam_usernamebot_limitbad_batch_sizebad_namebad_webhook_urlduplicate_namebad_bot_idbot_group_mismatchfield_not_supportedbad_configunknown_typetype_not_livebad_job_databot_busybot_needs_reloginbot_bannedbot_quarantinednot_cancellablebad_schedulebad_minutesno_targetsbad_targetduplicate_targettarget_not_foundbot_in_other_taskbad_state
Формат данных
- 64-битные идентификаторы (
steam_id,item_id) приходят строками: в число JavaScript они без потерь не помещаются. - Суммы приходят целым числом центов в полях
*_cents, валюта указана в полеcurrency. - Время в формате RFC 3339, в UTC. Исключение составляет
offer_timeу предложений дропа: это целое число из игры. - Пароль Steam, shared secret и identity secret можно только записать: API не возвращает их ни в одном ответе.
Операции
Для каждой операции указаны метод, путь, нужный скоуп и что она делает. Параметры и тело запроса показаны под строкой.
GET/public/v1/whoamiлюбой ключДанные ключа, которым сделан запрос.
Работает с любым действующим ключом, независимо от скоупов.
GET/public/v1/botsbots:readСписок учёток.
Строка запроса: limit, cursor, status, group_id, task_id
POST/public/v1/botsbots:credentialsДобавить учётку Steam.
Тело: PubBotCreate
Отправляйте
Idempotency-Key: без него повтор после обрыва сети получитduplicate_steam_usernameна учётку, которую добавил первый запрос. Пароль и секреты не возвращаются ни в одном ответе.POST/public/v1/bots/batchbots:credentialsДобавить до 200 учёток одним запросом.
Тело: PubBotBatchCreate
Отправляйте
Idempotency-Keyпо той же причине, что и при добавлении одной учётки. Каждая строка обрабатывается отдельно: ошибка в одной не отменяет остальные. Результаты сопоставляйте со строками запроса поindex.duplicate_in_batchвидит повторы только внутри одного запроса, поэтому уберите повторыsteam_usernameиз всего файла до того, как делить его на пачки. Иначе повтор из другой пачки придёт какduplicate_steam_username, как будто учётку добавили раньше.GET/public/v1/bots/{id}bots:readОдна учётка.
Путь: id
PATCH/public/v1/bots/{id}bots:writeПереименовать учётку.
Путь: id · Тело: PubBotUpdate
Меняется только
label. Пароль и shared secret меняются черезPUT /bots/{id}/credentials. Остальные поля в теле игнорируются.DELETE/public/v1/bots/{id}bots:writeУдалить учётку вместе с паролем и секретами.
Путь: id
PUT/public/v1/bots/{id}/credentialsbots:credentialsЗаменить пароль Steam или shared secret учётки.
Путь: id · Тело: PubBotCredentials
Передайте хотя бы одно из двух полей, пустое тело получит
bad_request. Учётка в статусеneeds_reloginпосле замены переходит вpending_login.GET/public/v1/bots/{id}/dropsbots:readПредметы учётки, сначала новые.
Путь: id · Строка запроса: limit, cursor
Доступны последние 500 предметов, по страницам.
GET/public/v1/bots/{id}/drop-offersbots:readПредложения дропа учётки, сначала новые.
Путь: id · Строка запроса: limit, cursor
Доступны последние 200 предложений, по страницам.
GET/public/v1/bots/{id}/matchesbots:readЗавершённые матчи учётки, сначала новые.
Путь: id · Строка запроса: limit, cursor
Доступны последние 200 матчей, по страницам.
GET/public/v1/accountaccount:readЗанятость слотов и действующие подписки.
GET/public/v1/account/overviewaccount:readСводка: дроп за неделю и по дням, последние дропы, матчи за сутки.
GET/public/v1/groupsbots:readСписок групп.
Строка запроса: limit, cursor
POST/public/v1/groupsbots:writeСоздать группу.
Тело: PubGroupCreate
У группы есть только имя и состав, настроек у неё нет.
GET/public/v1/groups/{id}bots:readОдна группа.
Путь: id
PATCH/public/v1/groups/{id}bots:writeПереименовать группу.
Путь: id · Тело: PubGroupUpdate
DELETE/public/v1/groups/{id}bots:writeУдалить группу.
Путь: id
Учётки остаются в кабинете. Группа пропадает из целей заданий, и её учётки выходят из заданий, куда попали через неё.
PUT/public/v1/groups/{id}/members/{bot_id}bots:writeДобавить учётку в группу.
Путь: id, bot_id
Повторное добавление учётки, которая уже в группе, ничего не меняет и ошибкой не считается. Чужая или несуществующая учётка или группа получает
404 not_found.DELETE/public/v1/groups/{id}/members/{bot_id}bots:writeУбрать учётку из группы.
Путь: id, bot_id
GET/public/v1/jobsbots:readСписок прогонов.
Строка запроса: limit, cursor, bot_id, state
По каждой учётке приходят текущий прогон и последний завершённый, то есть до двух записей. В список попадают прогоны любого типа, в том числе
cs2_farm, запущенные заданиями.POST/public/v1/jobsbots:writeЗабрать дроп учётки.
Тело: PubJobCreate
Принимается только
type: cs2_claim_drop. Наcs2_farmпридёт400 job_type_not_allowed: фарм запускают задания. Если у учётки уже есть активный прогон, придёт409 bot_busy. ОтправляйтеIdempotency-Key.GET/public/v1/jobs/capabilitiesbots:readПоля настроек задания.
Эти поля передаются в
configпри создании и правке задания (POST /tasks,PATCH /tasks/{id}). У забора дропа черезPOST /jobsнастроек нет.POST/public/v1/jobs/{id}/cancelbots:writeОтменить прогон.
Путь: id
Отменённый прогон не запустится снова. Идущий прогон останавливается не сразу.
GET/public/v1/taskstasks:readСписок заданий.
Строка запроса: limit, cursor
POST/public/v1/taskstasks:writeСоздать задание.
Тело: PubTaskInput
Отправляйте
Idempotency-Key. Цели можно оставить пустыми и добавить позже. Учётка может состоять только в одном активном или приостановленном задании, иначе придёт409 bot_in_other_taskсо списком заданий, где она уже есть.GET/public/v1/tasks/{id}tasks:readОдно задание.
Путь: id
PATCH/public/v1/tasks/{id}tasks:writeЗаменить задание целиком (имя, цели, расписание, настройки, минуты).
Путь: id · Тело: PubTaskInput
409 bot_in_other_taskприходит, только если правка добавляет учётку, которая уже состоит в другом активном или приостановленном задании.DELETE/public/v1/tasks/{id}tasks:writeУдалить задание.
Путь: id
Идущие матчи доигрываются, ожидающие прогоны снимаются.
POST/public/v1/tasks/{id}/pausetasks:writeПоставить задание на паузу.
Путь: id
Идущие матчи доигрываются, ожидающие прогоны снимаются. Учётки остаются за этим заданием.
POST/public/v1/tasks/{id}/resumetasks:writeСнять задание с паузы.
Путь: id
Если за время паузы из-за изменений в группах учётка оказалась ещё в одном активном или приостановленном задании, придёт
409 bot_in_other_task.POST/public/v1/tasks/{id}/stoptasks:writeОстановить задание и прервать идущие прогоны.
Путь: id
Задание встаёт на паузу, идущие прогоны прерываются, но не мгновенно. Прерванные прогоны не засчитываются учётке за неделю. У задания на паузе стоп прерывает матчи, которые ещё доигрываются.
Вебхуки
Вебхук отправляет POST-запрос на ваш адрес, когда что-то происходит с учёткой, дропом, прогоном, заданием или оплатой. Адреса заводятся и правятся только в кабинете, в разделе «API» → «Вебхуки».
До 5 адресов на пользователя. Адрес должен быть публичным и начинаться с https://, локальные и внутренние адреса не принимаются.
Тело запроса
В теле JSON с полями id (идентификатор события, по нему отсеивайте повторы), type (тип из таблицы ниже), created_at (время события) и data (данные события). Заголовок Content-Type: application/json.
Заголовки
| Заголовок | Значение |
|---|---|
X-Split-Event | Тип события, тот же, что в теле. |
X-Split-Delivery | Идентификатор доставки, одинаковый во всех повторах. |
X-Split-Signature | Подпись, см. раздел ниже. |
User-Agent | Всегда SplitTeam-Webhooks/1. |
Проверка подписи
X-Split-Signature содержит отметку времени и подпись: HMAC-SHA256 от строки «отметка времени, точка, тело запроса» в шестнадцатеричном виде. Формат заголовка показан ниже. Подпись считается от тела запроса в том виде, в каком оно пришло, до разбора JSON. Отклоняйте доставки с отметкой времени старше 5 минут и сравнивайте подпись функцией, время работы которой не зависит от содержимого: hmac.Equal в Go, crypto.timingSafeEqual в Node, hmac.compare_digest в Python.
t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
package splitwebhook
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"errors"
"math"
"strconv"
"strings"
"time"
)
// Verify checks the X-Split-Signature header against the RAW request body —
// before any JSON parsing, since the signature is computed over the exact
// bytes that were sent. header looks like "t=<unix seconds>,v1=<hex
// HMAC-SHA256(secret, "<t>.<raw body>")>".
func Verify(header string, body []byte, secret string, now time.Time) error {
var t, v1 string
for _, part := range strings.Split(header, ",") {
kv := strings.SplitN(part, "=", 2)
if len(kv) != 2 {
continue
}
switch kv[0] {
case "t":
t = kv[1]
case "v1":
v1 = kv[1]
}
}
if t == "" || v1 == "" {
return errors.New("malformed signature header")
}
ts, err := strconv.ParseInt(t, 10, 64)
if err != nil {
return errors.New("malformed timestamp")
}
// Reject a delivery older or newer than 5 minutes — this stops a
// captured delivery from being replayed later.
if age := now.Sub(time.Unix(ts, 0)); math.Abs(age.Seconds()) > 5*60 {
return errors.New("timestamp outside 5-minute tolerance")
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(body)
expected := hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(v1)) {
return errors.New("signature mismatch")
}
return nil
}import { createHmac, timingSafeEqual } from 'node:crypto';
/**
* Verifies the `X-Split-Signature` header of a Split Team webhook delivery
* against the RAW request body — before any JSON parsing, since the
* signature is computed over the exact bytes that were sent.
*
* The header looks like `t=<unix seconds>,v1=<hex HMAC-SHA256(secret,
* "<t>.<raw body>")>`. A delivery older or newer than `toleranceSeconds`
* (default 5 minutes) is rejected — that stops a captured delivery from
* being replayed later. `now` is only there so this same function can be
* exercised against fixed test vectors; leave it out in real code and it
* defaults to the current time.
*/
export function verifySplitSignature(
header: string,
rawBody: string | Buffer,
secret: string,
options: { toleranceSeconds?: number; now?: number } = {}
): boolean {
const toleranceSeconds = options.toleranceSeconds ?? 5 * 60;
const now = options.now ?? Date.now();
const parts = new Map(
header.split(',').map((pair) => {
const [key, value] = pair.split('=');
return [key, value] as const;
})
);
const t = parts.get('t');
const v1 = parts.get('v1');
if (!t || !v1) return false;
const timestamp = Number(t);
if (!Number.isFinite(timestamp)) return false;
if (Math.abs(now / 1000 - timestamp) > toleranceSeconds) return false;
const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody;
const expected = createHmac('sha256', secret).update(`${t}.`).update(body).digest('hex');
const expectedBuf = Buffer.from(expected, 'utf8');
const receivedBuf = Buffer.from(v1, 'utf8');
// Length check before timingSafeEqual: it throws on mismatched lengths
// instead of returning false, and a thrown error here must not be read
// as "signature valid" by a caller that only checks for an exception.
if (expectedBuf.length !== receivedBuf.length) return false;
return timingSafeEqual(expectedBuf, receivedBuf);
}import hashlib
import hmac
import time
def verify_split_signature(header, body, secret, now=None, tolerance_seconds=5 * 60):
"""Verifies X-Split-Signature against the RAW request body (bytes),
before any JSON parsing — the signature is computed over the exact
bytes that were sent. header looks like "t=<unix seconds>,v1=<hex
HMAC-SHA256(secret, "<t>.<raw body>")>".
"""
if now is None:
now = time.time()
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t"), parts.get("v1")
if not t or not v1:
return False
# Reject a delivery older or newer than 5 minutes — this stops a
# captured delivery from being replayed later.
if abs(now - int(t)) > tolerance_seconds:
return False
signed_payload = f"{t}.".encode() + body
expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)Успех, таймаут, редиректы
Доставка успешна, если ваш сервер ответил кодом 2xx за 10 секунд. Редиректы не выполняются: 3xx, как и любой код вне 2xx, считается отказом. Тело ответа не разбирается, в журнале доставок видно только его начало.
Повторы и автоотключение
Неудачная доставка повторяется через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч, затем раз в сутки. После девятой неудачной попытки, примерно через 2,9 суток после первой, повторы прекращаются.
Если с первого отказа прошло трое суток и за это время ни одна доставка на адрес не прошла, адрес отключается. Включить его снова можно в кабинете, и тогда ферма дошлёт доставки, повторы которых ещё не закончились. События, случившиеся, пока адрес был выключен, не отправляются и позже не придут: сверьте состояние через API (GET /bots, /jobs, /tasks).
Журнал доставок в кабинете хранит записи 7 дней, сами события хранятся 30 дней.
Минимум один раз, без порядка
Одно событие может прийти больше одного раза, а порядок разных событий не гарантирован. Отсеивайте повторы по id и считайте событие сигналом, что что-то изменилось: актуальное состояние читайте через API.
Типы событий
Кроме типов ниже есть ping: его отправляет кнопка «Отправить тестовое» в кабинете, подписываться на него не нужно.
| Тип | Когда | data |
|---|---|---|
bot.logged_in | Учётка готова к работе. | PubBot |
bot.needs_relogin | Steam не принял пароль или сессию, учётка снята с очереди. | PubBot |
bot.quarantined | Кик VACnet, бан или другой окончательный разрыв. | PubBot + code |
bot.cooldown | Матчмейкинг штрафует учётку временно. | PubBot + until |
drop.received | Учётка получила предмет недельного дропа. | PubDrop + bot_id |
drop.claimed | Ферма отправила запрос на забор предложения. | PubDropOffer + bot_id |
job.completed | Задание учётки закончилось успешно. | PubJob |
job.failed | Задание учётки закончилось отказом. | PubJob |
task.done | Задание владельца выполнено полностью. | PubTask |
payment.paid | Покупка слотов подтверждена платёжным шлюзом. | PubPayment |
subscription.expiring | Слоты закончатся в ближайшее время. | PubSubscription |
subscription.expired | Слоты по этой подписке больше не действуют. | PubSubscription |
Клиент
Спецификация OpenAPI доступна по ссылке ниже. По ней можно сгенерировать клиент, например openapi-typescript или openapi-generator.
Открыть openapi.yaml