навигация — сгруппировать аккаунты по смыслу («treasury», «payouts», «клиент-A») и фильтровать список по одному или нескольким тегам;
условие в политиках — правило может выбирать источник или назначение не перечислением аккаунтов, а по тегу: новый аккаунт с этим тегом попадает под правило автоматически, править политику не нужно.

Из чего состоит тег

Поле	Описание
`label`	Название, от 2 до 32 символов: латиница и кириллица, цифры, `_`, `-` и пробелы. Уникально в пределах workspace, пробелы по краям обрезаются.
`description`	Описание, до 255 символов. (необязательное поле)
`color`	Цвет, hex-код вида `#ff00ff`. Приводится к нижнему регистру. (необязательное поле)
`is_protected`	Признак защищённого тега — только для чтения. Такие теги участвуют в правилах политик и защищены от удаления, пока на них ссылается хотя бы одно правило.

Пустые значения

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

Защищённые теги пока не создаются

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

Привязка к аккаунтам

Привязка и отвязка выполняются одним запросом сразу для нескольких аккаунтов и нескольких тегов: в запросе указываются список аккаунтов, список тегов на привязку и список тегов на отвязку. Один и тот же тег нельзя одновременно привязывать и отвязывать.

Ограничение	Значение
Аккаунтов в одном запросе	1–100
Тегов на привязку в одном запросе	до 20
Тегов на отвязку в одном запросе	до 20
Тегов на одном аккаунте	до 20

Частичное применение

Запрос не отклоняется целиком, если часть пар «аккаунт + тег» применить нельзя. Ответ всегда содержит два списка:

applied_operations — что реально применилось;
rejected_operations — что не применилось.

{
  "applied_operations": [
    {
      "operation": "attach",
      "vault_id": "0f3a…", "vault_name": "Treasury",
      "tag_id": "b71c…", "tag_label": "treasury"
    }
  ],
  "rejected_operations": [
    { "operation": "attach", "vault_id": "9d21…", "tag_id": "b71c…" }
  ]
}

Пара попадает в rejected_operations, если:

аккаунта или тега нет в текущем workspace;
аккаунт заморожен — на замороженных аккаунтах теги не меняются (ни привязка, ни отвязка);
превышен лимит тегов на аккаунте — тогда для этого аккаунта пропускается привязка (отвязка при этом выполняется).

Повторная привязка уже привязанного тега ошибкой не считается: операция попадёт в applied_operations, состояние не изменится, а в журнал аудита ничего не добавится.

Список тегов

Читать теги можно двумя способами:

GET /tags — постраничный список с фильтрами: поиск по началу метки (label), отбор по is_protected и по конкретным tag_ids (до 100 значений), limit (по умолчанию 100) и offset;
GET /tags-list — все теги workspace одним ответом, без фильтров и пагинации: удобно для выпадающих списков в интерфейсе.

Обе ручки принимают сортировку:

Параметр	Значения
`order_by`	`label` (по умолчанию), `created_at`, `updated_at`, `is_protected`
`order_dir`	`asc` (по умолчанию) или `desc`

При любой сортировке метка служит вторичным ключом, поэтому порядок между страницами стабилен.

Аккаунты в ответе `GET /tags`

Вместе с каждым тегом приходит превью привязанных аккаунтов — не более пяти, самые новые. Сколько аккаунтов у тега на самом деле, показывает vaults_total; удалённые аккаунты не попадают ни в превью, ни в счётчик.

{
  "tags": [
    {
      "id": "b71c…",
      "label": "treasury",
      "description": null,
      "color": "#2f6feb",
      "is_protected": false,
      "vaults": [ { "id": "0f3a…", "name": "Treasury" } ],
      "vaults_total": 12
    }
  ],
  "total": 3,
  "offset": 0
}

Чтобы получить все аккаунты с нужным тегом, отфильтруйте список аккаунтов — см. ниже.

Фильтрация аккаунтов по тегам

Список аккаунтов можно отфильтровать по тегам, указав до 20 тегов и режим совпадения:

Режим	Что попадёт в выборку
`any` (по умолчанию)	Аккаунты, у которых есть хотя бы один из перечисленных тегов
`all`	Аккаунты, у которых есть все перечисленные теги

Режим без списка тегов — ошибка 400. В ответе каждый аккаунт приходит со своими тегами; у аккаунта без тегов это пустой список.

Теги в политиках

В правилах Transfer policy и AML-скрининга тег задаётся как условие на источник (source) или назначение (destination) вместе с режимом совпадения Any / All — семантика та же, что у фильтра аккаунтов. Ограничения:

тег нельзя комбинировать с «любой источник» / «любое назначение» и с «любой vault» — эти условия и так шире;
список тегов без режима совпадения (и наоборот) не принимается;
в правилах AML-скрининга сторона определяется направлением: для исходящих тег допустим только как источник, для входящих — только как назначение;
удалить тег, на который ссылается правило политики, нельзя — сначала измените правило.

Удаление тега

Удалить можно только тег, который никуда не привязан. Пока тег висит хотя бы на одном аккаунте, запрос вернёт 409 TAG_ATTACHED_TO_VAULT — сначала отвяжите тег от всех аккаунтов.

Код	HTTP	Когда
`TAG_NOT_FOUND`	`404`	Тега нет, он удалён или принадлежит другому workspace
`TAG_ALREADY_EXISTS`	`409`	Метка уже занята в этом workspace
`TAG_ATTACHED_TO_VAULT`	`409`	Тег привязан хотя бы к одному аккаунту
`TAG_IS_USED_IN_POLICY_RULE`	`409`	На тег ссылается правило политики

Управление через API

Все операции выполняются в контексте текущего workspace (заголовок X-Workspace-Id). Точные схемы запросов и ответов — в справочнике API.

Действие	Метод и путь	Право
Создать тег	`POST /tags`	`EDIT_WORKSPACE`
Список тегов	`GET /tags`	`VIEW_WORKSPACE`
Все теги workspace без пагинации	`GET /tags-list`	`VIEW_WORKSPACE`
Получить тег	`GET /tags/{tagId}`	`VIEW_WORKSPACE`
Изменить тег	`PATCH /tags/{tagId}`	`EDIT_WORKSPACE`
Удалить тег	`DELETE /tags/{tagId}`	`EDIT_WORKSPACE`
Привязать / отвязать теги	`POST /vault/tags`	`EDIT_WORKSPACE`
Аккаунты с фильтром по тегам	`GET /vault?tag_ids=…&tag_match_mode=any`	`VIEW_WORKSPACE`

Согласование изменений

В workspace может быть включено согласование для управления тегами: создание, изменение и удаление тега, привязка и отвязка отвечают 403 QUORUM_APPROVAL_REQUIRED с идентификатором запроса и применяются после одобрения. Изменение, которое ничего не меняет, выполняется сразу. Одобренные привязка и отвязка применяются к парам «аккаунт + тег», допустимым на момент применения, без списка отклонённых пар; если не применима ни одна, запрос закрывается с ошибкой.

Аудит

Все действия с тегами попадают в журнал аудита: создание, изменение и удаление тега, а также привязка тега к аккаунту и отвязка от него.

Теги