# Изменения API: 17 ноября 2026

[← Журнал изменений](/docs/changelog) · [Ноябрь 2026](/docs/changelog/2026-11)

### FIX-1117-1: повтор с тем же Idempotency-Key после смены ключа сервера больше не создаёт вторую машину

**Было**

При перепривязке сервера к другому ключу API платформа снимала с него значение `Idempotency-Key`. Повтор исходного запроса с тем же заголовком уже не находил созданную машину и создавал ещё одну: повтор тарифицировался как новое создание. То же происходило при передаче сервера другому пользователю и при восстановлении ключа.

**Стало**

Значение `Idempotency-Key` остаётся на сервере при перепривязке, передаче и восстановлении ключа. Повтор с тем же заголовком под ключом, который теперь управляет сервером, возвращает эту машину с заголовком ответа `Idempotent-Replayed: true`; успешный ответ остаётся HTTP 201, каким он был при создании. Область действия ключа не меняется — это по-прежнему один ключ API: повтор под прежним ключом связи с созданием не имеет.

**Влияние на интеграторов**

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

### NEW-1117-2: Отчёт о диске галактики

Метод `GET /v1/infra/servers/:id/disk-usage` возвращает сохранённый отчёт о диске галактики: данные приложений, остальные данные, образы, кеш сборки, изменяемые слои и журналы контейнеров. Можно передать идентификатор хоста или своего приложения. Ключ хоста видит все живые приложения, ключ приложения — только приложения того же ключа, а данные остальных объединены без имён. Запрос не будит хост и не запускает очистку. Если успешного снимка нет или указан обычный сервер, ответ содержит `data: null`.

В строке хоста `galaxy-reference` списка и карточки сервера появились `diskTotalMb`, `diskFreeMb`, `diskState` и `diskProbedAt`. В `access.allowedEndpoints` добавлен новый метод чтения отчёта. Подробнее — [отчёт о диске галактики](/docs/infra/servers/disk-usage).

### FIX-1117-3: подключение Компании не отключается при снятии прав администратора с держателя

**Было**

Подключение Компании переходило в `NEEDS_ADMIN`, если у держателя — сотрудника, давшего согласие как администратор, — снимали права администратора в Битрикс24: при плановой перепроверке или по событию смены роли. Пока перепроверка держателя не проходила, [GET /v1/connect/company/status](/docs/partner-connect) показывал `reason_code` `ADMIN_CHECK_REQUIRED` с действием `AUTHORIZE_ADMIN`, а рабочие вызовы Битрикс24 по секрету подключения получали HTTP 403 `CONNECTION_ADMIN_REQUIRED`.

**Стало**

Права администратора нужны только в момент согласия. После снятия прав подключение остаётся `ACTIVE` и работает с правами держателя как обычного сотрудника. В `NEEDS_ADMIN` подключение переходит, когда держатель уходит: его уволили, отключили или удалили, он стал гостем или больше не может авторизоваться своим ключом, что подтвердила повторная проверка не раньше чем через 30 секунд. Пока перепроверка держателя не прошла, статус показывает `reason_code` `ADMIN_CHECK_REQUIRED` с действием `WAIT`, а рабочие вызовы получают HTTP 503 `ADMIN_CHECK_REQUIRED` с заголовком `Retry-After`: повторите вызов позже. Ответ HTTP 200 на успешный вызов и опрос статуса не меняется, `NEEDS_ADMIN` по-прежнему даёт `CONNECTION_ADMIN_REQUIRED` и `AUTHORIZE_ADMIN`.

**Влияние на интеграторов**

Действий не требуется. Продукт, который следует полю `action` статуса, ждёт перепроверку вместо запроса администратора. На HTTP 503 `ADMIN_CHECK_REQUIRED` повторяйте вызов не раньше значения `Retry-After`.

### FIX-1117-4: поиск лида по внешним идентификаторам

**Было**

`GET /v1/leads` с `filter[originId]`, в том числе вместе с `filter[originatorId]`, возвращал `400 UNKNOWN_FILTER_FIELD`.

**Стало**

Оба строковых фильтра принимаются вместе для точного поиска лида по идентификаторам внешней системы и записи в ней. Ведущие нули сохраняются, `_` и `%` сравниваются буквально, в том числе при `$in` и передаче массива значений. Операторы `$ne`, `!` и `!=` задают точное неравенство вместо поиска по шаблону. Значение `originId` в ответе сохраняется без изменений, включая пустую строку.

### NEW-1117-5: Действия со списком чатов и начальная конфигурация

[Закрепить чат](/docs/chats/management/pin) и [открепить чат](/docs/chats/management/unpin) принимают необязательный `folderId` в JSON-теле для выбора области закрепа. Вызовы без поля сохраняют область по умолчанию.

[POST /v1/chats/:dialogId/hide](/docs/chats/management/hide) скрывает диалог в личном списке, сохраняя участие и сообщения. [GET /v1/chats/configuration](/docs/chats/discovery/configuration) рядом со счётчиками, папками и якорями отдаёт известные возможности списка, минимальные роли для действий, лимит закрепов в папке, допуск папочных действий платформы, ID и известный тип текущего пользователя без контактных данных. Отсутствующие сведения остаются неизвестными.

### NEW-1117-6: команды BitrixGPT в чатах

`POST /v1/chats/:dialogId/messages` принимает отдельное тело `command` с `kind: "copilot"` и `version: 1`: черновик и создание чата, ручная смена названия, модель и роль, остановка и повтор генерации, оценка, подсказки, действия форм и передача диктовки частями. Тело команды не смешивается с полями сообщения и параметрами строки запроса. Платформа не повторяет команду автоматически после неизвестного исхода.

`GET /v1/users/me?include=chatConfiguration` добавляет настройки чата, возможности BitrixGPT, права и запись бота BitrixGPT. Нужны скоупы `user` и `im`. Без `include` профиль сохраняет прежний состав.

`POST /v1/chats/:chatId/files/uploads/publish` поддерживает чаты BitrixGPT и необязательный объект `copilot` с параметрами сообщения.

### NEW-1117-7: Выбор показа приложения в Битрикс24

[POST /v1/infra/servers/:id/deploy](/docs/infra/deploy/deploy) принимает необязательный параметр `showInBitrix24`. Значение `false` позволяет развернуть приложение без карточки каталога и чата, `true` разрешает их создание. Параметр поддерживается в JSON и multipart, на отдельной виртуальной машине и у galaxy-приложения, а также при [POST /v1/infra/servers](/docs/infra/servers/create) с деплоем galaxy-приложения.

Первый выбор сохраняется. Следующий деплой с этим параметром выбор не меняет и добавляет в `warnings[]` предупреждение `SHOW_IN_BITRIX24_ALREADY_CHOSEN`.

[POST /v1/infra/servers/:id/b24-catalog/publish](/docs/infra/servers/b24-catalog-publish) сохраняет выбор `YES`. Новый [POST /v1/infra/servers/:id/b24-catalog/hide](/docs/infra/servers/b24-catalog-hide) сохраняет `NO`, убирает карточку и удаляет чат с историей. После повторной публикации чат будет новым и пустым.

[GET /v1/infra/servers/:id](/docs/infra/servers/get) и [GET /v1/infra/servers](/docs/infra/servers/list) возвращают `showInBitrix24` со значением `NOT_CHOSEN`, `YES` или `NO`. Политика доступа, выданные права и ссылки на приложение сохраняются.

### NEW-1117-8: сделки в режиме CRM API v3 по заголовку X-Crm-Api

CRM-маршруты принимают заголовок `X-Crm-Api: v2|v3`. В режиме `v3` маршруты сделок [GET /v1/deals](/docs/entities/deals/list), [GET /v1/deals/:id](/docs/entities/deals/get), [POST /v1/deals](/docs/entities/deals/create), [PATCH /v1/deals/:id](/docs/entities/deals/update), [DELETE /v1/deals/:id](/docs/entities/deals/delete), [POST /v1/deals/search](/docs/entities/deals/search) и [POST /v1/deals/aggregate](/docs/entities/deals/aggregate) работают через новую версию REST API Битрикс24 с прежними адресами и именами полей. Чего режим `v3` не умеет, получает отказ `422 CRM_V3_UNSUPPORTED` с `error.details.retryWith` — подсказкой повторить тот же запрос с заголовком `X-Crm-Api: v2`. Тот же отказ приходит, если на портале нет новой версии REST API Битрикс24. Ответ называет режим заголовком `X-Crm-Api`, когда запрос прислал этот заголовок или ключ работает в режиме `v3`. [GET /v1/me](/docs/keys-auth/me) отдаёт блок `crmApi` с режимом ключа. Существующие ключи остаются в режиме `v2`, и без заголовка их запросы работают как раньше. Режим, в котором портал выдаёт новые ключи, показывает поле `crmApi.newKeyMode`. Подробности — [Режимы CRM API](/docs/crm-api-modes).

### NEW-1117-9: Доставка ключа обслуживания агента по коду

При включённой на платформе доставке ключей обслуживания `GET /v1/me` с кодом описывает `kind: "agent_maintenance"`, а `POST /v1/key-claim` возвращает один ключ в `VIBE_MANAGEMENT_KEY`: JSON с `api_key`, `env_name`, `key_fingerprint`, `key` либо приватный dotenv с завершающим `# end`. Доступность зависит от включения на платформе.

Рецепт сохраняет ключ только в локальный `.env` обслуживающего агента. Проверка — локальный SHA-256 prefix16 и один запрос `GET /v1/infra/servers/:serverId/logs?service=hermes&lines=1` для Hermes либо `GET /v1/infra/servers/:serverId/logs?service=docker&lines=1` для OpenClaw с требованием HTTP `2xx`, `success: true` и непустого `data.logs`. `/v1/me` с самим ключом обслуживания по-прежнему возвращает `403 AGENT_MAINTENANCE_KEY_OUT_OF_SCOPE`; неудачная проверка не удаляет ключ и не требует его отзыва. Окружение приложения, сервера и MCP не меняется. См. [обмен и восстановление](/docs/keys-auth/me), [MCP](/docs/mcp), [инфраструктура](/docs/infra).

### BC-1117-10: вложенные маршруты сделок, лидов, контактов и компаний в режиме CRM API v3

> Поддержка старого формата до: не предусмотрена

**Было**

В режиме `v3` перевод на другую стадию и связи между записями — контакты сделки, лида и компании, компании контакта — выполнялись через прежнюю версию REST API Битрикс24, как в режиме `v2`. Список контактов сделки отдавал `sort` и `roleId`, перевод сделки на другую стадию отвечал сделкой со всеми полями прежней версии.

**Стало**

В режиме `v3` [POST /v1/deals/:id/move](/docs/entities/deals/move) и контакты сделки — [GET /v1/deals/:id/contacts](/docs/entities/deals/contacts-list), [POST /v1/deals/:id/contacts](/docs/entities/deals/contacts-create), [PUT /v1/deals/:id/contacts](/docs/entities/deals/contacts-set), [DELETE /v1/deals/:id/contacts/:relatedId](/docs/entities/deals/contacts-delete-delete) и [DELETE /v1/deals/:id/contacts](/docs/entities/deals/contacts-delete) — работают через новую версию REST API Битрикс24. Перевод сделки отвечает сделкой без полей, у которых нет пары в новой версии. У привязки контакта в новой версии нет порядка сортировки и роли: список контактов приходит без `sort` и `roleId`, основной контакт в нём первый, а `sort` и `roleId` в теле запроса получают отказ `422 CRM_V3_UNSUPPORTED`. Привязка с `isPrimary: true` выполняется двумя вызовами Битрикс24 и не атомарна: если второй вызов не прошёл, контакт остаётся привязанным, но не основным.

Перевод лида на другую стадию [POST /v1/leads/:id/move](/docs/entities/leads/move), контакты лида [GET /v1/leads/:id/contacts](/docs/entities/leads/contacts-list), контакты компании [GET /v1/companies/:id/contacts](/docs/entities/companies/contacts-list) и компании контакта [GET /v1/contacts/:id/companies](/docs/entities/contacts/companies-list) — вместе с их записью и отвязкой — в режиме `v3` отвечают `422 CRM_V3_UNSUPPORTED` с `error.details.retryWith`, подсказкой повторить запрос с заголовком `X-Crm-Api: v2`. В режиме `v2` все эти маршруты работают как раньше.

**Что делать интеграторам**

Если нужны `sort` и `roleId` контактов сделки, сделка со всеми полями прежней версии в ответе перевода на стадию или вложенные маршруты лидов, контактов и компаний, ключ в режиме `v3` отправляет на этих маршрутах заголовок `X-Crm-Api: v2`. Подробности — [Режимы CRM API](/docs/crm-api-modes) и раздел «Режим v3» страницы [Сделки](/docs/entities/deals).
