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

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

### NEW-1103-1: Письма и настройки CRM через API

API Вайбкод позволяет читать письма дел CRM, получать содержимое и цепочку переписки, отправлять письма и отвечать на них. Чтение доступно ключам со скоупом `crm`, отправка требует права записи и отправляет настоящее письмо. Не повторяйте отправку вслепую после неоднозначного сбоя.

[Настройки CRM](/docs/entities/crm-settings) доступны для чтения и изменения. Изменение действует на CRM всего портала. Значение передаётся целиком по схеме из ответа чтения. Ошибка чтения после записи не отменяет успешного изменения.

**Затронутые эндпоинты:** [GET /v1/crm-settings](/docs/entities/crm-settings/list), [GET /v1/crm-settings/:id](/docs/entities/crm-settings/get), [PATCH /v1/crm-settings/:id](/docs/entities/crm-settings/update), [GET /v1/deals/:id/emails](/docs/entities/crm-emails/list), [POST /v1/deals/:id/emails](/docs/entities/crm-emails/send), [GET /v1/crm-emails/:activityId](/docs/entities/crm-emails/get), [GET /v1/crm-emails/:activityId/thread](/docs/entities/crm-emails/thread), [POST /v1/crm-emails/:activityId/reply](/docs/entities/crm-emails/reply). Список и отправка также доступны для `leads`, `contacts`, `companies`. Существующий `GET /v1/crm-settings/mode` сохраняется.

### NEW-1103-2: Точечная правка значений полей CRM и основной контакт

Добавлены [операции значений полей](/docs/entities/crm-field-values): POST и DELETE `/v1/<ресурс>/:id/fields/:field/values` изменяют одно значение без замены всего списка. PUT `/v1/<ресурс>/:id/primary-contact` выбирает основной контакт из уже привязанных. Требуются скоуп `crm`, ключ с правом записи и включённая возможность `crm-rest-v3`.

Методы доступны при включении RestV3CrudDeal в обновлении Битрикс24 после `crm 26.2200.0`. Пока возможность недоступна, API отвечает `422 METHOD_NOT_YET_AVAILABLE` с `error.release`.

### NEW-1103-3: Обязательность полей CRM

`GET|PUT|DELETE /v1/{deals,leads,contacts,companies,quotes,invoices}/fields/required` и `/v1/items/:entityTypeId/fields/required` читают, устанавливают и снимают обязательность через REST v3. Скоуп `crm`. Изменения требуют `READWRITE` и меняют карточки и сохранение записей для всех пользователей портала. Пока возможность не включена или метод недоступен, возвращается `422 METHOD_NOT_YET_AVAILABLE` с линией выпуска в `error.release`.

### NEW-1103-4: Справочники CRM, варианты списочных полей, стадии воронок и режим лидов

В API Вайбкод добавлены чтение справочников CRM через `GET /v1/crm-dictionaries/:dictionary`, операции с отдельными вариантами списочных полей через `/v1/userfields/:entity/enum-values` и `/v1/items/:entityTypeId/userfields/enum-values`, замена стадий через `PUT /v1/deal-categories/:categoryId/stages` и `PUT /v1/categories/:entityTypeId/:categoryId/stages`.

`POST /v1/leads/enable` и `POST /v1/leads/disable` переключают весь портал между классическим и простым режимом CRM. Записи требуют `READWRITE`. Системные и финальные стадии сохраняются, удаление занятой стадии отклоняется.

Методы в процессе раскатки после `crm 26.2200.0`. Номер следующего выпуска ещё не опубликован. Пока возможность не включена или метод недоступен на портале, ответ — `422 METHOD_NOT_YET_AVAILABLE` с `error.release`.

### NEW-1103-5: Именованные раскладки карточки CRM

Именованные раскладки карточек CRM: [создание](/docs/entities/crm-card-layouts/add), [список](/docs/entities/crm-card-layouts/list), [чтение](/docs/entities/crm-card-layouts/get), [изменение](/docs/entities/crm-card-layouts/update), [удаление](/docs/entities/crm-card-layouts/delete), [выбор текущей](/docs/entities/crm-card-layouts/setcurrent) и ID [общей](/docs/entities/crm-card-layouts/getcommonlayoutid) и [личной](/docs/entities/crm-card-layouts/getpersonallayoutid) раскладки. Новые маршруты `/v1/crm/card-layouts/:entityType` используют скоуп `crm`, изменения требуют права записи. ID раскладки — строка, создание возвращает числовой ID.

В процессе раскатки: семейство появилось в `crm 26.1700.0`, доступность в облаке дополнительно зависит от включения возможности Битрикс24. До этого API отвечает `422 METHOD_NOT_YET_AVAILABLE` с `error.release`.

### FIX-1103-6: Длинное имя не блокирует управление ботом

**Было**

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

**Стало**

[`POST /v1/bots`](/docs/bots/management/create) и [`PATCH /v1/bots/:botId`](/docs/bots/management/update) отклоняют имя длиннее 50 кодовых точек Unicode с `400 BOT_NAME_TOO_LONG` до регистрации или обновления. Имя не обрезается. При обновлении проверяется фактически передаваемое имя — в плоском теле или в `fields.properties.name`, включая алиасы `PROPERTIES` и `NAME`. Передайте более короткое имя. Владелец отдельного бота, чьё переименование зависло после усечения имени до 50 кодовых точек Unicode, может вызвать обычный [`DELETE /v1/bots/:botId`](/docs/bots/management/delete) тем же API-ключом. Вайбкод отменяет незавершённое переименование только после подтверждённого отсутствия бота в Битрикс24. При смене владельца, ключа или регистрации, а также пока результат прежнего запроса ещё неизвестен, запись сохраняется и возвращается `409`. Этот путь не распространяется на ботов AI-агентов и управляемых ботов.

### BC-1103-7: fm не массивом и мультиполе с id в ключах больше не пропускаются молча

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

**Было**

У контактов, лидов и компаний сырой `fm` не массивом — объект, где ключи — `id` записей (`{"fm": {"11": {"typeId": "PHONE", "valueType": "WORK", "value": ""}}}`), строка, число, пустой объект или объект с ключами типов вида `PHONE`, — а также `phone`, `email` или `web` объектом с `id` записей в ключах (`{"phone": {"11": {"value": ""}}}`) или другим объектом без `value` — пустым или с ключами вроде `n0`, `0`, `011`, — числом, `true`/`false` или массивом с таким элементом (`{"phone": [{"11": {…}}]}`) принимались: изменение ([PATCH /v1/contacts/{id}](/docs/entities/contacts/update)) отвечало `200`, создание ([POST /v1/contacts](/docs/entities/contacts/create)) — `201`. Такое значение, а в массиве — только сам такой элемент, молча отбрасывалось и в Битрикс24 не передавалось, а остальные поля тела и остальные элементы массива записывались. Так же вели себя пакетные вызовы сущности, `/v1/batch` и импорт.

**Стало**

Такой запрос отклоняется до обращения к Битрикс24, и не записывается ничего, включая остальные поля тела. Объект, где ключи — `id` записей, в `fm`, `phone`, `email` или `web` — `400 MULTIFIELD_ID_NOT_SUPPORTED`. Сырой `fm` в другой форме, кроме массива `[{ "typeId", "valueType", "value" }]`, а также `phone`, `email` или `web` объектом без `value`, числом, `true`/`false` или массивом с таким элементом — `400 INVALID_MULTIFIELD_SHAPE`. `null`, пустой массив и пустые значения по-прежнему ничего не меняют. Проверка действует на одиночных вызовах, на пакетных вызовах сущности, на `/v1/batch` и на импорте.

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

Передавайте `fm` только массивом `[{ "typeId", "valueType", "value" }]`, а `phone`, `email` и `web` — строкой, массивом строк или массивом объектов `[{ "value", "typeId" }]` без `id`. Если интеграция шлёт такое значение вместе с другими полями или такой элемент рядом с рабочими элементами массива, уберите его: сам он и раньше не записывался, а теперь из-за него отклоняется весь запрос, включая рабочие элементы того же массива, которые раньше записывались. Изменить или удалить одну запись мультиполя по `id` через это API нельзя: отредактируйте карточку в интерфейсе Битрикс24.

### FIX-1103-8: Схемы чтения сделок, контактов и пользователей учитывают незаполненные поля

**Было**

В `/v1/openapi.json` часть полей ответа была объявлена только строкой, числом или датой. Успешные ответы уже возвращали `null`, например в `previousStageId` и `probability` сделки, но проверка по опубликованной схеме их отвергала.

**Стало**

Схемы чтения разрешают `null` для следующих полей:

- Сделки: `comments`, `lastCommunicationTime`, `lastCommunicationCallTime`, `lastCommunicationEmailTime`, `lastCommunicationImolTime`, `lastCommunicationWebformTime`, `previousStageId`, `probability`, `sourceDescription`, `sourceId`.
- Контакты: `comments`, `lastCommunicationTime`, `lastCommunicationCallTime`, `lastCommunicationEmailTime`, `lastCommunicationImolTime`, `lastCommunicationWebformTime`, `name`, `lastName`, `secondName`, `post`, `sourceDescription`, `typeId`.
- Пользователи: `lastActivityDate`, `lastLogin`, `personalBirthday`, `timestampX`.

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

Значения в ответах и правила записи не изменились. После обновления сгенерированных моделей учитывайте `null` у этих полей. Пропущенное необязательное поле и присутствующее поле со значением `null` остаются разными случаями. Ограничение имени контакта в 50 символов сохраняется.

**Затронутые эндпоинты:** [GET /v1/deals](/docs/entities/deals/list), [GET /v1/contacts](/docs/entities/contacts/list), [GET /v1/users](/docs/entities/users/list). Те же схемы используются при чтении отдельных записей и в операциях, возвращающих эти записи.

### NEW-1103-10: Версионный протокол расшифровки файлов чата

[POST /v1/chats/files/:fileId/transcribe](/docs/chats/files/transcribe) принимает парные необязательные поля `requestId` (UUID) и `contentVersion` (1–128 печатных ASCII-символов без пробелов). Неполная или некорректная пара отклоняется с `400 INVALID_PARAMS`, вызовы без обоих полей сохраняют прежний формат запроса и ответа.

`GET /v1/chats/transcription/config` со скоупом `im` возвращает только проверенный descriptor protocol 1, без состояния звонков и учётных данных. Оба вызова требуют пишущего ключа: чтение исходной конфигурации может создавать системные папки. Ключ только для чтения получает `403 WRITE_BLOCKED_READONLY_KEY` до обращения к Битрикс24. Поддержка зависит от Битрикс24; если descriptor отсутствует или некорректен, ответ — `422 BITRIX_ERROR` с `error.b24Code` = `TRANSCRIPTION_NOT_ACTIVE`.

### FIX-1103-11: Одна попытка запуска расшифровки файла

**Было**

[POST /v1/chats/files/:fileId/transcribe](/docs/chats/files/transcribe) без пары `requestId` и `contentVersion` мог автоматически повторять обращение к Битрикс24 после отказа или перенаправления.

**Стало**

Запуск расшифровки обращается к Битрикс24 не более одного раза для обоих форматов запроса. Автоматические повторы, исправление скоупов вебхука и переходы по перенаправлениям отключены. Формат запроса и ответа сохранён.

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

Ошибку первой попытки API возвращает вызывающему приложению. Новую попытку запускает пользователь.

### FIX-1103-12: Списки CRM tracking и traces сообщают о недоступном методе

**Было:** Списочные GET в `/v1/crm-tracking` и `/v1/crm-traces` отвечали `500 INTERNAL_ERROR`, если на стороне Битрикс24 метод REST v3 ещё не был доступен.

**Стало:** Те же запросы отвечают `422 METHOD_NOT_YET_AVAILABLE` с `error.release`, как обещает документация.

### NEW-1103-13: подсказка портала в ссылке авторизации Connect

[GET /v1/connect/authorize](/docs/partner-connect/authorize) принимает необязательный параметр `portal` — домен портала Битрикс24, например `portal=mycompany.bitrix24.ru`. Если пользователь — активный участник этого портала, портал выбран на странице согласия заранее. Пользователь может сменить выбор, и ключ выдаётся на тот портал, который он подтвердил. Некорректное значение не вызывает ошибку: вход идёт как без параметра. Ответ `authorize` от параметра не зависит. Подсказку учитывает поток с кодом авторизации для клиентов в режиме `PERSONAL`.

### NEW-1103-14: настройка входа пользователей называет порядок шагов для SDK 0.4

`GET /v1/app-user-signin/servers/{serverId}/setup` отдаёт новое поле `enableFlow`, когда приложению этого сервера раздаётся SDK входа 0.4 или новее: `enabled` — вход приложения уже включён, `steps` — что сделать, по порядку. Секрет и переменные входа в этом случае доставляет платформа, поэтому `env` пуст. Ответ для более ранних версий SDK прежний, поля `enableFlow` в нём нет.
