Контейнеры

Контейнеры-хранилища на сервере, их владельцы, инвентарь и счётчики типов.

Каждый контейнер-хранилище на сервере — список с пагинацией, один контейнер по его entity id, его инвентарь и разбивка по количеству каждого типа.

Идентификация контейнера

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

GET /v1/containers
GET /v1/containers/5
GET /v1/containers/5/inventory
GET /v1/containers/types

Авторизация

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

Каждый owner контейнера несёт discord_id (null, если владелец не привязан к Discord). Ключ без скоупа получает 403 insufficient_scope.

`GET /v1/containers`

Список контейнеров с пагинацией. Необязательные фильтры:

Параметр	Значение
`owner_steam_id`	Контейнеры этого Steam64 (только цифры).
`owner_discord_id`	Контейнеры игрока, привязанного к этому Discord id (только цифры). Резолвится в момент запроса; непривязанный id ничего не находит (пустая страница, не `404`).
`owner_name`	Точное совпадение имени персонажа владельца (оператора подстроки нет).
`base_id`	Контейнеры на этой базе (только цифры).
`is_locked`	`true` или `false`.
`is_buried`	`true` или `false`.
`search`	Текстовый поиск. Нельзя сочетать со структурным фильтром выше (`400 validation_error`).
`limit`	Размер страницы, 10–100 (по умолчанию 50).
`cursor`	Непрозрачный курсор из `next_cursor` предыдущего ответа.

Передать оба owner_steam_id и owner_discord_id — 400 validation_error.

{
  "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": true, "lock_type": "DialLock_Item", "lock_hp": 0.5, "is_buried": false,
      "last_access_time": "2023-11-14T22:13:20.000Z", "item_count": 4
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 1
}

Про поля

owner — вложенный объект идентичности { profile_id, name, steam_id, discord_id }. lock_hp и каждая ось position — дробные числа. last_access_time — ISO-8601 (или null). item_count — null, если мод его не передал.

`GET /v1/containers/{id}`

Один контейнер по его entity id. Возвращает тот же объект, что и строка списка. 404 not_found, если контейнера с таким entity id нет.

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

Полный вложенный инвентарь контейнера. Каждый предмет может нести contents (рекурсивно). Поддерево, которое мод перестал раскрывать на пределе глубины, помечается contents_truncated: true.

{
  "items": [
    {
      "id": 7, "class": "Rifle", "name": "Rifle", "icon": "…",
      "health": 90, "max_health": 100, "weight": 3, "is_container": false, "is_weapon": true,
      "contents_truncated": false,
      "contents": [ { "id": 8, "class": "Mag", "name": "Mag", "icon": "…", "contents": [], "contents_truncated": true, "health": 1, "max_health": 1, "weight": 0.2, "is_container": true, "is_weapon": false } ]
    }
  ],
  "total": 1
}

`GET /v1/containers/types`

Агрегация только для чтения: сколько контейнеров каждого отображаемого имени существует. Это сводка, а не источник для фильтра — числа привязаны к человекочитаемым именам, а не к сырому class_name, который передают в фильтр.

{ "types": { "Crate": 5, "Wooden Locker": 2 } }

Кэширование

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

Ошибки

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

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

Контейнеры

Содержание