Сквады

Списки сквадов, участники, сводная статистика и базы, транспорт и контейнеры сквада.

Всё о сквадах на сервере — список, отдельный сквад, его участники (со статистикой), сводные итоги и базы, транспорт и контейнеры, которыми владеют участники.

Идентификация сквада

Каждый эндпоинт по скваду принимает числовой сегмент пути {id} — id сквада из SCUM. Это положительное целое без ведущих нулей (шаблон ^[1-9]\d*$); значения вроде 0 и 007 отклоняются с 400 validation_error.

GET /v1/squads/5
GET /v1/squads/5/members

В списке сквад можно найти и по лидеру, по любому идентификатору:

?leader_steam_id=76561198000000000
?leader_discord_id=123456789012345678

leader_discord_id разрешается в привязанного игрока на момент запроса; непривязанный id просто ничего не находит (пустая страница, а не 404). Указать сразу и leader_steam_id, и leader_discord_id — это 400 validation_error.

Авторизация

Скоуп	Даёт
`squads:read`	Все эндпоинты сквадов — список, детали, участники, сводка, базы, транспорт, контейнеры.

У каждого участника и у лидера есть discord_id (null, если игрок не привязан). Ключ без нужного скоупа получает 403 insufficient_scope.

`GET /v1/squads`

Список сквадов с пагинацией. Опциональные фильтры:

Параметр	Смысл
`leader_steam_id`	Сквады под лидерством этого Steam64 (только цифры).
`leader_discord_id`	Сквады под лидерством игрока, привязанного к этому Discord-id (только цифры).
`min_members` / `max_members`	Ограничить число участников.
`min_score`	Минимальный счёт сквада.
`active_within_days`	Только сквады, у которых последний вход участника был за последние N дней. Целое число ≥ 1.
`search`	Поиск по имени. Нельзя сочетать со структурным фильтром выше (`400 validation_error`).
`limit`	Размер страницы, 10–100 (по умолчанию 50).
`cursor`	Непрозрачный курсор из `next_cursor` предыдущего ответа.

Возвращает конверт-коллекцию. total — число сквадов, подходящих под запрос (по всем страницам):

{
  "data": [
    {
      "id": 5,
      "name": "Wolves",
      "score": 12.5,
      "member_limit": 8,
      "member_count": 4,
      "leader": { "id": 7, "steam_id": "76561198000000000", "discord_id": "123456789012345678", "name": "Bob" },
      "last_active": "2024-01-01 12:00:00"
    }
  ],
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

Про поля

score — дробное число. last_active — сырая серверная метка времени в том виде, как её хранит SCUM (не ISO-8601). discord_id лидера — null, если лидер не привязан к Discord.

`GET /v1/squads/{id}`

Отдельный сквад — та же форма объекта, что и строка списка.

`GET /v1/squads/{id}/members`

Полный состав (ограничен лимитом участников сквада, поэтому без пагинации). У каждого участника — боевая статистика, экономика и привязка к Discord.

{
  "data": [
    {
      "id": 9, "profile_id": 7,
      "steam_id": "76561198000000000", "discord_id": "123456789012345678",
      "steam_name": "Bob", "char_name": "Bobby",
      "rank": 4, "kills": 3, "deaths": 1,
      "cash": 500, "bank_money": 1000, "gold": 5, "fame_points": 42,
      "online": true, "last_logout": "2024-01-01 09:00:00"
    }
  ]
}

rank: 4 = лидер, 3 = офицер, 2 = участник, 1 = рекрут.

`GET /v1/squads/{id}/summary`

Сводные итоги по участникам сквада.

{
  "squad_id": 5,
  "total_kills": 10, "total_deaths": 4,
  "total_cash": 5000, "total_bank_money": 20000, "total_gold": 30, "total_fame": 999,
  "total_containers": 12, "total_vehicles": 3,
  "member_count": 4
}

`GET /v1/squads/{id}/bases`

Базы участников сквада, с пагинацией limit (1–100) и cursor.

{
  "data": [
    {
      "flag_id": 1, "base_id": 2,
      "owner": { "profile_id": 7, "name": "Bob", "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
      "max_elements": 100, "element_count": 40, "avg_health": 87.5,
      "position": { "x": 1.5, "y": 2.5, "z": 3.5 }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

`GET /v1/squads/{id}/vehicles`

Транспорт участников сквада, с пагинацией limit (1–100) и cursor.

{
  "data": [
    {
      "entity_id": "99", "class_name": "BPC_Kinglet_Duster", "display_name": "Kinglet Duster",
      "owner": { "profile_id": 7, "name": "Bob", "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
      "health": 950.5, "max_health": 1000,
      "position": { "x": 1, "y": 2, "z": 3 },
      "is_locked": true, "lock_type": "DialLock_Item", "lock_hp": 0.85,
      "is_functional": true, "last_access_time": "2023-11-14T22:13:20.000Z", "item_count": 12
    }
  ],
  "has_more": false,
  "next_cursor": null
}

`GET /v1/squads/{id}/containers`

Контейнеры участников сквада, с пагинацией limit (1–100) и cursor.

{
  "data": [
    {
      "entity_id": "5", "class_name": "Crate", "display_name": "Crate", "custom_name": "Loot",
      "owner": { "profile_id": 7, "name": "Bob", "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
      "base_id": 2, "base_name": "HQ",
      "position": { "x": 1, "y": 2, "z": 3 },
      "is_locked": false, "lock_type": null, "lock_hp": 0, "is_buried": false,
      "last_access_time": null, "item_count": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Про поля

Каждый owner актива — вложенный объект идентичности { profile_id, name, steam_id, discord_id }; discord_id — null, если владелец не привязан к Discord. avg_health, health, max_health, lock_hp и каждая ось position — дробные числа. last_access_time — ISO-8601 (или null). item_count — null, если мод его не передал. Списки активов не несут поле total — листайте по next_cursor.

Кэширование

Каждое чтение сквада отдаёт ETag и Cache-Control: private с коротким max-age (10–15 с); верните ETag в If-None-Match, чтобы получить 304 Not Modified. Ничего из этого не no-store.

Ошибки

Стандартный конверт ошибки. Самые вероятные:

Код	Статус	Когда
`insufficient_scope`	403	У ключа нет `squads:read`.
`not_found`	404	Под `{id}` нет сквада.
`validation_error`	400	`{id}` не является положительным целым без ведущих нулей (`^[1-9]\d*$`), `?search=` со структурным фильтром, оба leader-id сразу, или не-цифровой `leader_steam_id`/`leader_discord_id`.
`server_unavailable`	503	Игровой сервер офлайн или недоступен.
`gateway_timeout`	504	Сервер не ответил вовремя.

Сквады

Содержание