Публичный 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_key
  • insufficient_scope
  • rate_limited
  • internal
  • bad_idempotency_key
  • idempotency_key_reused
  • idempotency_in_progress
  • not_found
  • bad_limit
  • bad_cursor
  • bad_request
  • method_not_allowed
  • job_type_not_allowed
  • bad_game_id
  • bad_label
  • bad_steam_username
  • bad_steam_password
  • bad_steam_shared_secret
  • bad_steam_identity_secret
  • duplicate_steam_username
  • bot_limit
  • bad_batch_size
  • bad_name
  • bad_webhook_url
  • duplicate_name
  • bad_bot_id
  • bot_group_mismatch
  • field_not_supported
  • bad_config
  • unknown_type
  • type_not_live
  • bad_job_data
  • bot_busy
  • bot_needs_relogin
  • bot_banned
  • bot_quarantined
  • not_cancellable
  • bad_schedule
  • bad_minutes
  • no_targets
  • bad_target
  • duplicate_target
  • target_not_found
  • bot_in_other_task
  • bad_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/bots
    bots:read

    Список учёток.

    Строка запроса: limit, cursor, status, group_id, task_id

  • POST/public/v1/bots
    bots:credentials

    Добавить учётку Steam.

    Тело: PubBotCreate

    Отправляйте Idempotency-Key: без него повтор после обрыва сети получит duplicate_steam_username на учётку, которую добавил первый запрос. Пароль и секреты не возвращаются ни в одном ответе.

  • POST/public/v1/bots/batch
    bots: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}/credentials
    bots:credentials

    Заменить пароль Steam или shared secret учётки.

    Путь: id · Тело: PubBotCredentials

    Передайте хотя бы одно из двух полей, пустое тело получит bad_request. Учётка в статусе needs_relogin после замены переходит в pending_login.

  • GET/public/v1/bots/{id}/drops
    bots:read

    Предметы учётки, сначала новые.

    Путь: id · Строка запроса: limit, cursor

    Доступны последние 500 предметов, по страницам.

  • GET/public/v1/bots/{id}/drop-offers
    bots:read

    Предложения дропа учётки, сначала новые.

    Путь: id · Строка запроса: limit, cursor

    Доступны последние 200 предложений, по страницам.

  • GET/public/v1/bots/{id}/matches
    bots:read

    Завершённые матчи учётки, сначала новые.

    Путь: id · Строка запроса: limit, cursor

    Доступны последние 200 матчей, по страницам.

  • GET/public/v1/account
    account:read

    Занятость слотов и действующие подписки.

  • GET/public/v1/account/overview
    account:read

    Сводка: дроп за неделю и по дням, последние дропы, матчи за сутки.

  • GET/public/v1/groups
    bots:read

    Список групп.

    Строка запроса: limit, cursor

  • POST/public/v1/groups
    bots: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/jobs
    bots:read

    Список прогонов.

    Строка запроса: limit, cursor, bot_id, state

    По каждой учётке приходят текущий прогон и последний завершённый, то есть до двух записей. В список попадают прогоны любого типа, в том числе cs2_farm, запущенные заданиями.

  • POST/public/v1/jobs
    bots:write

    Забрать дроп учётки.

    Тело: PubJobCreate

    Принимается только type: cs2_claim_drop. На cs2_farm придёт 400 job_type_not_allowed: фарм запускают задания. Если у учётки уже есть активный прогон, придёт 409 bot_busy. Отправляйте Idempotency-Key.

  • GET/public/v1/jobs/capabilities
    bots:read

    Поля настроек задания.

    Эти поля передаются в config при создании и правке задания (POST /tasks, PATCH /tasks/{id}). У забора дропа через POST /jobs настроек нет.

  • POST/public/v1/jobs/{id}/cancel
    bots:write

    Отменить прогон.

    Путь: id

    Отменённый прогон не запустится снова. Идущий прогон останавливается не сразу.

  • GET/public/v1/tasks
    tasks:read

    Список заданий.

    Строка запроса: limit, cursor

  • POST/public/v1/tasks
    tasks: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}/pause
    tasks:write

    Поставить задание на паузу.

    Путь: id

    Идущие матчи доигрываются, ожидающие прогоны снимаются. Учётки остаются за этим заданием.

  • POST/public/v1/tasks/{id}/resume
    tasks:write

    Снять задание с паузы.

    Путь: id

    Если за время паузы из-за изменений в группах учётка оказалась ещё в одном активном или приостановленном задании, придёт 409 bot_in_other_task.

  • POST/public/v1/tasks/{id}/stop
    tasks: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>")>
Go
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
}
Node
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);
}
Python
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_reloginSteam не принял пароль или сессию, учётка снята с очереди.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