# Изменения API: 1 октября 2026

[← Журнал изменений](/docs/changelog) · [Октябрь 2026](/docs/changelog/2026-10)

### NEW-1001-1: Управление to-do и сроками дел CRM

Создание и изменение to-do дел CRM доступно через [POST /v1/activity-todos](/docs/entities/activities/todos/create) и [PATCH /v1/activity-todos/:id](/docs/entities/activities/todos/update). Для любого дела добавлены действия: [завершить](/docs/entities/activities/complete), [отложить](/docs/entities/activities/postpone) и [перенести срок](/docs/entities/activities/deadline). Чтение и список дел остаются в `/v1/activities`.

### NEW-1001-2: чтение CRM-форм

API Вайбкод предоставляет `GET /v1/crm-forms` и `GET /v1/crm-forms/:id`: список форм и безопасное описание полей формы. Для чтения нужен ключ со скоупом `crm`; настройки captcha и интеграций не выдаются.

### NEW-1001-3: Поиск по CRM и реквизитам по номеру

Добавлены `POST /v1/crm/search` для поиска по типам CRM с указанием тарифных ограничений и `POST /v1/requisites/lookup` для получения полей реквизитов по номеру и пресету.

### BC-1001-4: машинные ссылки на файлы CRM требуют ключ API Вайбкод

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

**Было**

Машинные адреса в файловых полях CRM и в документах Битрикс24 содержали доступ к скачиванию без ключа API Вайбкод.

**Стало**

Поля `urlMachine`, `downloadUrlMachine`, `pdfUrlMachine`, `imageUrlMachine` и `downloadMachine` сохраняют имена, но для доступных файлов ведут на адрес API Вайбкод. Без `X-Api-Key` файл больше не открывается. У документа или шаблона без проверенного маршрута машинное поле отсутствует. Ссылки для браузера сохраняются.
Скачивание по HTTP-адресу коробочного портала теперь отклоняется с 502: для передачи файлов и учётных данных настройте HTTPS.

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

Передавайте тот же ключ с нужным скоупом при переходе по машинной ссылке. См. [файлы CRM](/docs/recipes/crm-files), [документы CRM](/docs/entities/documents/crm-list) и [шаблоны](/docs/entities/doc-templates/download).

### NEW-1001-5: скачивание файлов CRM и документов через API Вайбкод

Файлы полей CRM доступны через [маршрут скачивания](/docs/recipes/crm-files), готовые CRM-документы — как [DOCX](/docs/entities/documents/download), [PDF](/docs/entities/documents/pdf) и [изображение](/docs/entities/documents/image). [REST-шаблоны](/docs/entities/doc-templates/download) тоже скачиваются с ключом API Вайбкод. Принимаются ключи READONLY с нужным скоупом.

### NEW-1001-6: Оплаты CRM с товарными позициями и чтение доставок

Добавлены `/v1/crm-payments` и `/v1/crm-deliveries` со скоупом `crm`. Оплату можно создать прямо по сделке: Битрикс24 сам создаёт связанный заказ. Товарные позиции добавляются отдельно, после чего Битрикс24 пересчитывает сумму. Метка оплаты может запускать автоматизации портала.

### NEW-1001-7: создание и управление CRM-документами через API Вайбкод

Теперь документ по сделке или другой записи CRM можно создать из шаблона, получить, обновить, удалить и загрузить через [маршруты CRM-документов](/docs/entities/documents). Публичную ссылку можно включить и отключить отдельным действием. Файлы скачиваются через защищённые маршруты с ключом API Вайбкод.

### NEW-1001-8: отказ по размеру файла при загрузке несёт подсказку

Ответы `413 IMAGE_TOO_LARGE` у [POST /v1/feedback/attachments](/docs/feedback/attachments) и `413 STORAGE_UPLOAD_TOO_LARGE` у [POST /v1/storage/objects/upload](/docs/storage/upload/direct) получили необязательное поле `error.hint` с текстом на английском о том, что делать дальше: уменьшить изображение либо перейти на составную загрузку. Сообщение `error.message` у `IMAGE_TOO_LARGE` теперь называет предел в 10 МБ. Коды и статусы прежние, клиентам, которые читают только `error.code`, менять ничего не нужно.

### FIX-1001-9: ключ Коворка больше не отказывает служебной записи коробки

**Было**

Ротация ключа Коворка и `PATCH /v1/keys/:id` могли ответить `403 COWORK_BOX_SERVICE_ACCOUNT_DENIED`, если владелец ключа вошёл из коробочного портала без учётной записи Битрикс24.

**Стало**

Служебных записей коробки больше нет, поэтому ротация и `PATCH /v1/keys/:id` не отвечают `403 COWORK_BOX_SERVICE_ACCOUNT_DENIED`.

### NEW-1001-10: CRM-шаблоны документов доступны через API Вайбкод

[Новые маршруты](/docs/entities/crm-document-templates) позволяют получить, создать, изменить и удалить шаблоны CRM, найти шаблоны для конкретной записи и скачать исходный DOCX по ключу API Вайбкод со скоупом `crm`.

### NEW-1001-11: причина, действие и текст для человека в отказах по скоупу ключа

Отказы по скоупу самого ключа API несут новые необязательные поля: `error.cause` со значением `key_scope_missing`, `error.requiredScope` — недостающий скоуп, `error.keyScopes` — скоупы ключа в этом запросе, `error.fix`, `error.hint` и `error.userMessage` — текст для человека, который можно показать как есть. Поля приходят в `403 INSUFFICIENT_SCOPE` маршрутов `/v1/cowork/*`, в `403 INFRA_SCOPE_REQUIRED`, в `403 SCOPE_NOT_ALLOWED` пакетного запроса и в `403 SCOPE_DENIED` маршрутов сущностей (включая их пакетные и агрегатные вызовы и `include`), записей таймлайна и открытых линий. `error.fix.action` — `edit_key_scopes`, когда скоуп можно добавить ключу в кабинете, `reissue_key` — для ключа OAuth-приложения из раздела «Приложения», иначе `none`. Ключу, выданному через Partner Connect, `edit_key_scopes` не приходит: набор его прав фиксирует согласие пользователя, и поддерживаемый путь — повторное согласие, которое проводит приложение. В пакетном запросе элементы `data.errors` с кодом `SCOPE_NOT_ALLOWED` несут `cause`, `requiredScope`, `fix` и `hint`, а `keyScopes` и `userMessage` приходят только в самом ответе `403`. `403 SCOPE_DENIED` редактора бизнес-процессов, когда скоуп отклонил сам Битрикс24, несёт `error.cause` = `b24_scope`. Код, статус и `error.message` не изменились. Разбор — [Авторизация, ключи и права](/docs/errors/auth#scope_denied-403).

### FIX-1001-12: отказ Битрикс24 по скоупу больше не называет ключ из кабинета ключом платформы

**Было**

Ответы `403 BITRIX_ACCESS_DENIED` и `422 BITRIX_ERROR` с `error.cause` = `b24_scope` для части ключей, созданных в кабинете, и для ключей, выданных через Partner Connect, несли `error.hint` о том, что ключ ведёт платформа и его скоупы не правятся из кабинета. То же утверждение получали ключи, которые платформа выпустила под конкретную задачу (Cowork/Code, обслуживание сервера, доступ соавтора), хотя их скоупы в кабинете правятся.

**Стало**

`error.fix.action` по-прежнему `none`. `error.hint` говорит, как есть: для части ключей, созданных в кабинете, ответ не знает, выдан ли ключ через Partner Connect, — у такого ключа набор прав фиксирует согласие пользователя, — поэтому добавить скоуп ключу он не советует; для ключа, выпущенного платформой под конкретную задачу, — что подействует ли добавление скоупа, не определено. Коды, статусы и `error.message` не изменились. Разбор — [Авторизация, ключи и права](/docs/errors/auth#bitrix_access_denied-403).

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

Действий не требуется: `error.fix` не изменился, меняется только текст `error.hint`.

### BC-1001-13: Подтверждение расширения доступа к приложениям

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

**Было**

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

- [PATCH /v1/infra/servers/{id}/access-policy](/docs/infra/access/access-policy) — изменение политики доступа.
- [POST /v1/infra/servers/{id}/access](/docs/infra/access/access-add) — добавление пользователя или отдела.
- [DELETE /v1/infra/servers/{id}/access/{accessId}](/docs/infra/access/access-delete) — удаление записи, если итоговое восстановление других прав расширяет аудиторию.
- [POST /v1/infra/servers/{id}/access-tokens](/docs/infra/access-tokens/create) — выпуск токена.

**Стало**

На защищённых порталах машинные запросы, расширяющие доступ к приложению, требуют подтверждения человеком. Первый запрос возвращает `409 AUDIENCE_APPROVAL_REQUIRED`, не меняя доступ; в ответе передаются ссылка на проверку и точная операция для повтора. После подтверждения повторите запрос с теми же учётными данными и `approvalId`. При повторном выпуске токена используйте зафиксированный абсолютный `expiresAt` без пересчёта `ttlSeconds`. Учётные данные инициатора позволяют получить или отменить собственные заявки, но не подтвердить их.

Первое и повторное развёртывание сохраняют аудиторию, права доступа и учётные данные. Чтение, доказанное сужение доступа и обновление bearer-токена без тела запроса продолжают работать по существующим правилам авторизации. [PATCH /v1/infra/servers/{id}/mode](/docs/infra/access/mode): машинные запросы на OPEN отклоняются до сетевых операций; прямой доступ включает человек через кабинет с проверенной сессией.


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

Обрабатывайте `409 AUDIENCE_APPROVAL_REQUIRED`: покажите человеку ссылку на проверку и дождитесь подтверждения. Затем повторите точную операцию с `approvalId` и исходными учётными данными; для токена передайте исходный абсолютный `expiresAt`. Машинный OPEN замените действием человека в кабинете. Для удаления записи доступа передайте `approvalId` в строке запроса: `DELETE /v1/infra/servers/{id}/access/{accessId}?approvalId=APPROVAL_ID`. Автоматический повтор без подтверждения не расширяет доступ. Период поддержки прежнего поведения не предусмотрен.

### BC-1001-14: запись мультиполя с id отклоняется на всех дверях записи

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

**Было**

Объект с полем `id` в `phone`, `email`, `web` или в сыром массиве `fm[]` принимался и уходил в Битрикс24. На изменении ([PATCH /v1/contacts/{id}](/docs/entities/contacts/update), а также лиды и компании, пакетные вызовы и `/v1/batch`) Битрикс24 поле `id` игнорирует и добавляет ВТОРУЮ запись: вызов отвечал `200`, а у контакта появлялся дубль телефона. Попытка удалить запись формой `{ "id": 11, "value": "" }` отвечала `200`, не делая ничего. На создании ([POST /v1/contacts](/docs/entities/contacts/create), пакеты, импорт) `id` молча отбрасывался.

**Стало**

Такой запрос отклоняется до обращения к Битрикс24: `400 MULTIFIELD_ID_NOT_SUPPORTED`, ничего не записывается. Текст ошибки разный по двери: на изменении он объясняет, что Битрикс24 игнорирует `id` и добавил бы дубль, на создании — что идентификаторы записей мультиполя Битрикс24 назначает сам. Проверка покрывает `phone`, `email`, `web` и сырой `fm[]` на одиночных вызовах, на пакетных вызовах сущности, на `/v1/batch` и на импорте.

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

Шлите запись мультиполя без `id` — так добавляется новое значение. Заменить или удалить отдельный телефон или email через это API нельзя: отредактируйте карточку в интерфейсе Битрикс24.

### NEW-1001-15: Справочники CRM, режим и локализации валют

Добавлены GET /v1/crm-enums/owner-types, GET /v1/crm-enums/address-types, GET /v1/crm-settings/mode, GET /v1/statuses/entity-types, GET /v1/requisite-presets/countries и GET /v1/currencies/base. Они помогают выбрать тип сущности, адреса, справочник статусов, страну шаблона и узнать, включены ли лиды.

GET, PUT и DELETE /v1/currencies/:id/localizations читают, записывают и удаляют настройки отображения валют по языкам. GET /v1/currencies/:id/localizations/fields перечисляет допустимые camelCase-поля. Пустой ввод и неизвестные поля отбиваются до Б24; существование валюты проверяется до локализации, запись и удаление подтверждаются чтением. Смена базовой валюты не добавлена.

### NEW-1001-18: поле recentCallsDataSince в GET /v1/ai/usage

Ответ [`GET /v1/ai/usage`](/docs/ai/consumption/usage) получил поле `data.recentCallsDataSince` — границу построчной истории вызовов в `ISO 8601`. Построчная история хранится не меньше 35 суток: если ключ старше этой границы, поле содержит её дату, и вызовов раньше неё в `recentCalls` нет — пустой массив тогда означает «вызовов после границы не было». `null` — история ключа доступна целиком. Счётчики `totals`, `byModel` и `byScope` граница не затрагивает, остальные поля ответа не изменились.

### BC-1001-19: смена режима ключей места Коворка через V1 и перевыпуск ключа шире вызывающего отбиваются 403

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

**Было**

`PATCH /v1/keys/:id` с полем `mode` на ключе десктопа Коворка и на ключе стороннего агента на подписке Коворка отвечал HTTP 200 и менял режим одной строки ключа. `POST /v1/cowork/applications/:id/key` на приложении, чей ключ в слоте шире вызывающего, отвечал HTTP 201 и выписывал новый ключ в прежнем, более широком режиме.

**Стало**

Режим ключа Коворка — это режим места «человек + портал», один на все его устройства. `PATCH /v1/keys/:id` со сменой `mode` на ключе десктопа Коворка отвечает 403 `COWORK_SEAT_KEY_MODE_CABINET_ONLY`. На ключе стороннего агента запрос режима шире места отвечает 403 `COWORK_KEY_MODE_ABOVE_SEAT`, в пределах места правка работает как раньше. Запрос с ТЕМ ЖЕ `mode`, который шлют ради переименования, изменением не считается и проходит: ответ остаётся HTTP 200. `POST /v1/cowork/applications/:id/key` на приложении, чей ключ в слоте шире вызывающего, отвечает 403 `KEY_ROTATE_WIDER_THAN_CALLER` вместо выдачи ключа шире вызывающего.

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

Режим места меняйте в разделе «API-ключи» веб-кабинета правкой ключа десктопа Коворка: там видно, что сузится вместе с местом. Получили `COWORK_KEY_MODE_ABOVE_SEAT` — сначала расширьте место, затем повторите правку ключа стороннего агента. Получили `KEY_ROTATE_WIDER_THAN_CALLER` — перевыпустите ключ приложения в веб-кабинете.

### BC-1001-20: ключи, которые выпускает место Коворка, не шире режима места

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

**Было**

`POST /v1/cowork/deploy-key` выписывал ключ деплоя в режиме «чтение и запись» при любом режиме ключей десктопа этой пары. `POST /v1/apps` под ключом деплоя с явным `mode` выдавал парный ключ приложения в запрошенном режиме.

**Стало**

Ключи, которые выпускает место Коворка, не шире режима места «человек + портал». Ключ деплоя выходит в самом узком из режима вызывающего ключа и режима места. `POST /v1/apps` под ключом места — таков ключ деплоя — выдаёт парный ключ не шире режима места: явный запрос шире одного лишь места выдаёт ключ в режиме места без отказа, ответ остаётся HTTP 201. Окно со старым поведением не предусмотрено: потолок места — граница, которую выбрал его владелец, и окно её бы отменило.

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

Если интеграции нужен ключ деплоя или ключ приложения с правом записи, а место в режиме «только чтение», расширьте место: смените режим ключа десктопа Коворка в разделе «API-ключи» веб-кабинета. Режим выписанного ключа деплоя называет поле `accessMode` ответа `POST /v1/cowork/deploy-key`.

### NEW-1001-21: POST /v1/cowork/deploy-key называет режим выписанного ключа

Ответ `POST /v1/cowork/deploy-key` несёт новое поле `accessMode` — режим выписанного ключа деплоя. Он никогда не шире вызывающего ключа и не шире режима места Коворка этой пары: ключ деплоя — инструмент места, поэтому у места в режиме «только чтение» он выходит таким же. Прежние поля ответа не менялись.

### FIX-1001-22: приложение и ключ в пустой слот выдаются в режиме вызывающего вместо 403

**Было**

`POST /v1/apps` без поля `mode` под ключом «только чтение» на портале с политикой «чтение и запись» отвечал 403. `GET /v1/cowork/applications/defaults` показывал режим одной политики портала, хотя создание выдавало ключ не шире вызывающего. `POST /v1/cowork/applications/:id/key` на пустом слоте под политикой «только чтение» отвечал 403 `KEY_POLICY_READONLY_REQUIRED`.

**Стало**

`POST /v1/apps` без `mode` выдаёт приложение в самом узком из режима политики и режима вызывающего ключа; явный запрос режима шире вызывающего по-прежнему отвечает 403 `WRITE_BLOCKED_READONLY_KEY`. `GET /v1/cowork/applications/defaults` показывает режим, который действительно выдаст создание. Выдача в пустой слот выписывает ключ в самом узком из режима политики и режима вызывающего вместо 403; `KEY_POLICY_READONLY_REQUIRED` на этой ручке остаётся только за ключом участника команды разработки, если выдаваемый ключ шире политики. Пока включён запрет записи для ключей «только чтение» (по умолчанию он включён), такому вызывающему ключу сами `POST /v1/cowork/applications` и `POST /v1/cowork/applications/:id/key` отвечают 403 `WRITE_BLOCKED_READONLY_KEY` раньше остальных проверок: для такого ключа `defaults` показывает потолок, а не обещание выдачи.

### FIX-1001-23: ключу стороннего агента больше не советуют получить ключ деплоя

**Было**

[GET /v1/me](/docs/keys-auth/me) под ключом подписки Коворк/Код, выписанным для сторонней агентной программы, называл в блоке `deployment` эндпоинт [POST /v1/cowork/deploy-key](/docs/cowork/deploy-key) с порядком получения ключа деплоя и отдавал поле `deployment.deployKeyEndpoint`, а примечания слотов серверов и приложений в `capabilities` советовали тот же эндпоинт. Тот же совет такой ключ получал в `error.details.requiredAction` отказа `403 INFRA_FORBIDDEN_FOR_COWORK_KEY`, а [GET /v1/guide](/docs/keys-auth/guide) советовал получить ключ деплоя в `infraApi.coworkKeyNotice` без оговорок. Сам эндпоинт такому ключу отвечает `403 COWORK_HARNESS_KEY_FORBIDDEN`.

**Стало**

Такому ключу `deployment.howToDeploy`, примечания слотов в `capabilities` и `error.details.requiredAction` отказа `403 INFRA_FORBIDDEN_FOR_COWORK_KEY` говорят, что ключ деплоя ему не выдаётся (`403 COWORK_HARNESS_KEY_FORBIDDEN`), а доставлять приложения нужно из настольного приложения Коворк/Код или обычным ключом со скоупом `vibe:infra`. Поля `deployment.deployKeyEndpoint` у такого ключа нет. `infraApi.coworkKeyNotice` и описание эндпоинта в путеводителе несут то же исключение для ключа стороннего агента. Ответы `/v1/me` и `/v1/guide` по-прежнему HTTP 200, код и статус отказа `403 INFRA_FORBIDDEN_FOR_COWORK_KEY` не изменились, у остальных ключей тексты прежние.

### FIX-1001-24: rotatable и rotateBlockedReason учитывают режим вызывающего ключа

**Было**

Блок `key` карточки приложения (`GET /v1/applications`, `GET /v1/applications/:id`) считал `rotatable` без режима вызывающего ключа: карточка обещала `rotatable: true` там, где `POST /v1/cowork/applications/:id/key` отвечал отказом.

**Стало**

`rotatable` и `rotateBlockedReason` учитывают режим вызывающего ключа: `rotatable` становится `false`, а в `rotateBlockedReason` приходит `WIDER_THAN_CALLER`, когда ключ в слоте шире вызывающего, и `WRITE_BLOCKED_READONLY_KEY`, когда ключ вызывающего не меняет данные и включён запрет записи для таких ключей. Ответ по-прежнему HTTP 200; незнакомую причину клиент читает как «заменить нельзя, причина неизвестна».

### FIX-1001-25: изменение to-do не перезаписывает параллельные правки

**Было**

[PATCH /v1/activity-todos/:id](/docs/entities/activities/todos/update) с полем, у которого нет точечного метода Битрикс24 (например, `title` или `pingOffsets`), передавал заголовок, описание, срок, напоминания и ответственного из чтения, сделанного за несколько обращений к Битрикс24 до записи. Если в этот промежуток дело правил другой пользователь или параллельный запрос, его правка перезаписывалась прежним значением. Если текущего ответственного нельзя было назначить повторно, такой PATCH завершался ошибкой, хотя ответственного в запросе не было.

**Стало**

Значения полей, которых нет в запросе, читаются перед самой записью. Ответственный передаётся, только если он есть в запросе. Успешный ответ остаётся HTTP 200. Существующий код `422 ACTIVITY_UPDATE_NOT_APPLIED` теперь возвращается и в новом случае: после записи поле, которого нет в запросе, отличается от значения, прочитанного перед записью.

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

Действий не требуется. Правка, сохранённая в деле до начала записи, как правило сохраняется при PATCH другого поля. Получив `422 ACTIVITY_UPDATE_NOT_APPLIED` с упоминанием полей вне запроса, проверьте дело: запись выполнена, но одно из этих полей изменилось.

### BC-1001-27: строковые параметры больше не принимают массивы и объекты

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

**Было**

Некоторые строковые параметры публичных V1-эндпоинтов неявно преобразовывали массивы и объекты в строки. В частности, это затрагивало фильтры `sha256`, идентификаторы папок и подразделений, курсор коллекций заметок, `model`, лимиты, параметры подписки на события и `PROTOCOL` обработчика размещения.

**Стало**

Параметры, объявленные строковыми или числовыми скалярами, принимают только соответствующие скалярные значения. Массивы и объекты получают предусмотренный конкретным эндпоинтом отказ либо обрабатываются как отсутствующий необязательный параметр. HTTP-режим обработчика размещения включается только строковым значением `PROTOCOL='0'`.

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

Передавайте перечисленные параметры как одиночные строки или числа согласно документации. Не используйте скобочную форму запроса и JSON-массивы или объекты вместо скалярных значений.

**Затронутые эндпоинты:** [GET /v1/apps/:id/sources](/docs/source-storage/versions), [GET /v1/infra/servers/:id/sources](/docs/source-storage/servers), [POST /v1/files/:id/moveto](/docs/entities/files/moveto), [POST /v1/files/:id/copyto](/docs/entities/files/copyto), [POST /v1/folders/:id/moveto](/docs/entities/folders/moveto), [POST /v1/folders/:id/copyto](/docs/entities/folders/copyto), [POST /v1/humanresources/nodes/search](/docs/humanresources/nodes/search), [POST /v1/infra/servers/:id/event-subscriptions](/docs/infra/event-subscriptions/create), [GET /v1/note/collections](/docs/note/collections/list), [GET /v1/off-peak](/docs/ai/consumption/off-peak), [GET /v1/mail/messages](/docs/mail/messages/list), [POST /v1/bitrix-handler](/docs/infra/app-runtime).

### BC-1001-28: ссылки на скачивание файлов Диска требуют ключ API Вайбкод

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

**Было**

Поле `downloadUrl` в ответах о файлах Диска и в метаданных файлов чата содержало адрес Битрикс24 с доступом к порталу, который открывался без ключа API Вайбкод.

**Стало**

Поле `downloadUrl` сохраняет имя и для файла с идентификатором ведёт на [`GET /v1/files/:id/download`](/docs/entities/files/download). Без `X-Api-Key` файл по нему не скачивается. Ключу только со скоупом `im` для перехода по ссылке из [метаданных файла чата](/docs/chats/files/file-get) нужен ещё скоуп `disk` или `crm`. Ссылка на страницу файла в Битрикс24 (`detailUrl`) сохраняется.

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

Передавайте тот же ключ при переходе по `downloadUrl`. Сохранённые адреса Битрикс24 из прежних ответов замените новыми из повторного запроса.

### NEW-1001-29: внешний API приложения работает с сервером в режиме «по расписанию»

Сервер в [режиме «по расписанию»](/docs/infra/lifecycle/run-mode) теперь допускается во внешний API приложения `ANY /v1/applications/:id/api/**`, если его тариф не вытесняемый. Ответ зависит от состояния сервера. Запущенный сервер принимает вызов — в окнах [расписания работы](/docs/infra/work-schedules) и после конца окна, пока он не уснул по простою; такие вызовы продлевают его работу, а это время оплачивает владелец приложения. Спящий сервер вне окна отвечает новым кодом `409 APP_API_OUTSIDE_SCHEDULE` с заголовком `Retry-After` — числом секунд до начала ближайшего окна; повторите вызов после этого срока. Если срок вычислить нельзя (например, расписание сервера удалено), заголовка нет, и повтор по времени не поможет — проверьте расписание сервера. `503 APP_API_UNAVAILABLE` получают сервер, пробуждение которого запрещено (например, приостановлено по оплате), и сервер, который не запущен и не спит вне окна: ещё просыпается к началу окна, остановлен, в ошибке или ещё создаётся. Переключатель «Внешний API» у такого сервера включается, пока сервер запущен и его пробуждение не запрещено. Решения на таком сервере подчиняются тому же правилу: пока сервер запущен, публикация контракта решения и вызов решения проходят; к спящему вне окна серверу публикация не проходит, а вызов решения получает `SOLUTION_UNAVAILABLE`. Серверов без расписания изменение не касается. Подробнее — [Внешний API приложения](/docs/applications/external-api).

### BC-1001-30: Явный отказ для дублирующихся и отсутствующих CRM-связей

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

**Было**

POST уже существующей связи контакта сделки или компании возвращал успешный список; DELETE отсутствующей связи возвращал 204.

**Стало**

POST возвращает 409 RELATION_ALREADY_EXISTS, если Б24 отвечает false. DELETE отсутствующей связи возвращает 404 ENTITY_NOT_FOUND. То же поведение действует для новых связей контакта с компаниями и лида с контактами. Клиентам нужно обрабатывать эти статусы вместо прежнего успешного ответа.

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

Обрабатывайте 409 при повторной привязке и 404 при повторной отвязке; для идемпотентной очистки всего списка используйте DELETE коллекции.

### NEW-1001-31: Связи компаний контакта, контактов лида и очистка всех связей

GET / POST / PUT `/v1/contacts/:id/companies` и `/v1/leads/:id/contacts`, DELETE с `/:relatedId` отвязывает одну запись. DELETE коллекции очищает связи у контактов, лидов, сделок и компаний с ответом 204. Старые `include=company` и `include=contact` сохраняют одиночную форму; новые имена `companyBinding` и `contactBinding` разрешают все связи.

### NEW-1001-32: причина смены статуса в ленте активности сервера

В событиях `server.status_changed` ленты `GET /v1/infra/servers/{id}/activity` появилось необязательное поле `meta.reason`. Сейчас оно бывает одно — `billing_freeze`: сервер уснул из-за заморозки по балансу. У остальных смен статуса поля нет; прежние запросы работают как раньше.

### NEW-1001-33: Право pull_channel доступно на включённых порталах

На порталах, где включена поддержка канала Pull, право `pull_channel` можно выбрать при создании ключа или приложения. Порталы без поддержки не показывают право в выборе и не добавляют его к новым ключам.

### NEW-1001-34: Обзвоны контактов и компаний

Добавлены `GET /v1/call-lists`, `GET /v1/call-lists/:id`, `POST /v1/call-lists`, `PUT /v1/call-lists/:id`, `GET /v1/call-lists/:id/items` и `GET /v1/call-lists/statuses`. PUT полностью заменяет состав и сбрасывает неуказанный webformId. Записи возвращают id и skipped по видимому перечитыванию участников. Создание также создаёт дело «Обзвон»; удалить список через REST нельзя. Дата сохраняется без часового пояса. Несуществующие списки дают 404 ENTITY_NOT_FOUND, бизнес-отказы Б24 — 422 BITRIX_ERROR. READONLY-ключи на записи получают 403 WRITE_BLOCKED_READONLY_KEY.

### NEW-1001-35: Регулярные сделки и создание сделки по шаблону

Регулярные сделки: добавлены `/v1/recurring-deals` с созданием, чтением, изменением, удалением, полями, поиском и пакетными операциями. `POST /v1/recurring-deals/:id/expose` создаёт сделку по шаблону и возвращает её ID и ссылку. При настройке обычной сделки Битрикс24 создаёт отдельный шаблон-копию; ответ содержит фактический `dealId`. Доступность зависит от тарифа Битрикс24.

### FIX-1001-36: перенос старого дела-задачи больше не даёт ложный 422

**Было**

`POST /v1/activities/{id}/postpone` для старого дела-задачи (`TYPE_ID=3`) с устаревшим непустым `PROVIDER_ID` отвечал 422 `ACTIVITY_POSTPONE_NOT_APPLIED`, хотя Битрикс24 переносил срок связанной задачи.

**Стало**

Такое дело обрабатывается как дело провайдера `TASKS`: ответ HTTP 200 с перечитанным делом, время самого дела при этом может остаться прежним. Для остальных дел проверка сохраняется, и несдвинутое время по-прежнему даёт 422 `ACTIVITY_POSTPONE_NOT_APPLIED`. См. [перенос дела](/docs/entities/activities/postpone).

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

Действий не требуется. Обход ошибки 422 для таких дел больше не нужен.

### NEW-1001-37: Загрузка файлов в чат без немедленной публикации

API Вайбкод добавил [POST /v1/chats/:chatId/files/uploads](/docs/chats/files/upload-to-folder) для загрузки в папку без сообщения, [POST /v1/chats/files/uploads/status](/docs/chats/files/upload-status) для проверки наличия, [POST /v1/chats/:chatId/files/uploads/discard](/docs/chats/files/upload-discard) для уборки и [POST /v1/chats/:chatId/files/uploads/publish](/docs/chats/files/upload-publish) для публикации нескольких файлов одним сообщением. Загрузка доступна начиная с выпуска `im 26.1500.0`; до его установки на портале маршрут отвечает `422 METHOD_NOT_YET_AVAILABLE`. Существующий [POST /v1/chats/:chatId/files](/docs/chats/files/upload) работает как прежде.

### FIX-1001-38: Свой ключ DeepSeek или OpenAI-совместимого провайдера получает имя модели без префикса каталога

**Было**

Запрос `POST /v1/chat/completions` с моделью `deepseek/deepseek-v4-pro` или `custom-openai-compat/<модель>` на своём ключе провайдера уходил провайдеру с префиксом каталога, например `deepseek/deepseek-v4-pro`. Провайдер такого имени не знает и отклонял вызов.

**Стало**

Провайдеру уходит имя модели без префикса своего провайдера: `deepseek-v4-pro`, `<модель>`. Если у модели в каталоге задан собственный идентификатор провайдера, он по-прежнему уходит без изменений. Модели `openai/…` работают как раньше.

### NEW-1001-39: Следы сквозной аналитики CRM

[POST /v1/crm-traces](/docs/entities/crm-traces/create) создаёт след посетителя из JSON-объекта или JSON-строки. Можно привязать его к лидам, сделкам, контактам, компаниям и предложениям. Записи проверяются перед добавлением. [DELETE /v1/crm-traces/:id](/docs/entities/crm-traces/delete) отвечает 204 идемпотентно, без подтверждения существования следа или удаления всех привязок. Требуются скоуп `crm` и ключ READWRITE.

### NEW-1001-40: GET /v1/me отдельно заявляет о запрете менять данные Битрикс24

У ключа в режиме «только чтение» ответ [GET /v1/me](/docs/keys-auth/me) несёт второе заявление о запрете — новое корневое поле `portalWriteRestriction`, про изменение данных Битрикс24. В нём код `WRITE_BLOCKED_READONLY_KEY`, область, список закрытых маршрутов с условием отказа у каждой записи и ссылка на страницу режима. В отличие от соседнего `writeRestriction`, которое описывает платформенные записи, поле приходит и тогда, когда платформенный запрет записи снят: данные Битрикс24 такой ключ не меняет в любом случае. У ключа приложения блок `placements` получает поле `note` — границу встраивания для ключа, которому запись в данные Битрикс24 закрыта. В подсказках `portalEmbedding` личного ключа `READONLY` все встройки, включая `LEFT_MENU`, отмечены недоступными даже при снятом платформенном запрете. Подсказки `READWRITE` прежние. Подробнее — [Режим доступа](/docs/keys-auth/access-mode).

### FIX-1001-41: повтор опроса событий бота сразу после отказа по самому боту больше не получает 409

**Было**

Если бот успевал измениться между началом опроса и его выполнением — например, его выключили или передали другому ключу, — `GET /v1/bots/:botId/events` отдавал отказ (`410 BOT_DISABLED`, `403 BOT_ACCESS_DENIED` или `404 BOT_NOT_FOUND`) раньше, чем опрос этого бота считался завершённым. Немедленный повторный опрос мог получить `409 BOT_EVENTS_BUSY` вместо того же отказа.

**Стало**

Отказ отдаётся только после завершения опроса, поэтому повторный опрос сразу получает тот же отказ. Коды и статусы ошибок не изменились, успешный ответ HTTP 200 тоже прежний.

### NEW-1001-42: Контроль времени и участники рабочих графиков

Добавлены чтение и изменение настроек контроля времени, месячные отчёты об отсутствиях, список сотрудников отдела и объяснение отсутствия в `/v1/workday/time-control/*`. Для объяснения обязательны месяц и год отсутствия. Настройки изменяются на весь портал; IP-адреса в отчётах — персональные данные. `/v1/workday/schedules/:id` позволяет удалить график, а `/v1/workday/schedules/:id/users` — включить сотрудника. DELETE `/v1/workday/schedules/:id/users/:userId` исключает сотрудника и снимает будущие смены; другие графики сохраняются. Все операции требуют `timeman`.

### NEW-1001-43: причина, действие и текст для человека в SCOPE_DENIED маршрутов чатов, CRM, календаря и других областей

`403 SCOPE_DENIED` по скоупу самого ключа API на маршрутах активностей, адресов, бронирований, ботов, календаря, звонков, обзвонов, складских документов и изображений товаров каталога, чатов, платежей, доставок, документов, форм, поиска, карточек, справочников и трассировок CRM, файлов и папок диска, шаблонов документов, оргструктуры, списков и почты несёт те же необязательные поля, что и отказы генерируемых маршрутов сущностей: `error.cause` со значением `key_scope_missing`, `error.requiredScope` — недостающий скоуп, `error.keyScopes` — скоупы ключа в этом запросе, `error.fix` — действие, `error.hint` — пояснение на английском и `error.userMessage` — текст для человека, который можно показать как есть. Если маршруту нужны два скоупа, `error.requiredScope` называет первый недостающий; если хватает любого из двух, — первый в порядке проверки. Код, статус и `error.message` не изменились. Разбор — [Авторизация, ключи и права](/docs/errors/auth#scope_denied-403).

### NEW-1001-44: Справочники заказа и свойства позиций корзины

Добавлены /v1/person-types, /v1/order-properties и /v1/basket-item-properties: чтение, создание, обновление и удаление со скоупом sale. Доступны поиск, статическая схема полей, агрегация и пакетные операции. Y/N-флаги представлены как boolean.

В PATCH свойства заказа type, personTypeId и propsGroupId readonly. Неуказанные поля, настройки, привязки оплаты/доставки и варианты ENUM сохраняются. FILE с существующим файлом defaultValue требует явной замены при PATCH (иначе 400). settings принимает только объект; в batch — не более одного обновления свойства заказа за запрос. Для свойств позиций basketId readonly в PATCH. Запись свойства позиции пересохраняет весь заказ в Битрикс24.

### NEW-1001-45: обмен токена Атласа на ключ Коворка и его продление

`POST /v1/connect/atlas/token` обменивает access-токен Атласа на ключ Коворка. Запрос несёт `Authorization: DPoP <access>` и заголовок `DPoP` с proof ключа устройства. В теле обязателен `client_id` клиента Коворка. Необязательный `device_id` в допустимом формате привязывает ключ к установке и после выдачи гасит прежние ключи этой установки. Иной `device_id` выдачу не отменяет: ключ выходит без привязки к установке. Успех — `200` и тело `{api_key, expires_at}`. `expires_at` — это `exp` токена, в секундах.

`POST /v1/connect/atlas/renew` продлевает уже выданный ключ свежим токеном того же человека и того же устройства. К тем же заголовкам добавляется `X-Api-Key` с продлеваемым ключом. Строка ключа не меняется. Успех — `200` и тело `{expires_at}`: срок сдвигается только вперёд, до `exp` нового токена, и не становится короче уже записанного.

Отказ проверки токена или proof — `401`. Заголовок `WWW-Authenticate: DPoP` называет `error` `invalid_token` или `invalid_dpop_proof`. Тело этого отказа и отказов ниже, кроме лимита частоты адреса, — `{error, error_description}`. `400` `invalid_request` — нет `client_id` на обмене или нет `X-Api-Key` на продлении. `400` `invalid_client` бывает только на обмене: клиент неизвестен, выключен или это не клиент Коворка.

`403` `atlas_source_unsupported` — личность не человек портала или портал не коробочный. `403` `atlas_portal_unknown` — токен не называет портал, который знает платформа. `403` `atlas_user_not_linked` — у пользователя портала ещё нет учётной записи на платформе. `403` `atlas_user_unavailable` несёт `details.reason`: `blocked`, `deleted`, `erasing` или `member_gone`. `403` `atlas_identity_changed` несёт `details.reason`: `atlas_subject_changed` или `portal_occupant_changed`. `403` `atlas_key_mismatch` бывает только на продлении: ключ выдан другой личности или другому устройству.

Если отказывает сама выдача ключа, поле `error` несёт тот же код, который device flow Connect отдаёт в поле `code`: `503` `COWORK_DISABLED`, `403` `COWORK_KEY_GATED`, `403` `COWORK_HIDDEN` (в `details.requestable` — можно ли подать заявку), `403` `ACCESS_DENIED`, `403` `COWORK_SUB_PAUSED`, `403` `COWORK_SUB_CANCELLED`, `409` `B24_USER_DELETED`, `500` `ISSUANCE_FAILED`.

`429` `too_many_requests` с заголовком `Retry-After` — у одной личности Атласа больше пяти обменов за десять минут. Продление этот предел не тратит. Отдельно оба адреса ограничивают частоту запросов с одного адреса. Сверх предела ответ `429` в конверте V1, `error.code` равен `RATE_LIMITED`, есть заголовок `Retry-After`. Действующее значение для ключа — заголовок `x-ratelimit-limit`. Потолок платформы — 30 запросов в минуту на адрес, и он делится между репликами.

`503` `temporarily_unavailable` с заголовком `Retry-After` — ключи издателя или проверка одноразовости proof временно недоступны.

### NEW-1001-46: Отгрузки и позиции отгрузок

- `/v1/shipments` и `/v1/shipment-items`: создание, чтение, поиск, обновление и удаление отгрузок и их позиций со scope `sale`.
- `POST /v1/shipments/:id/ship` и `/unship`: отметка об отгрузке с перечитанной записью в ответе; складской учёт может списывать остатки.
- PATCH отгрузки сохраняет поля, которые Б24 сбрасывает при отсутствии в теле. `deducted` readonly; batch отгрузок отключён для предотвращения потери данных.

### NEW-1001-47: причина, действие и текст для человека в отказах по скоупу ключа маршрутов задач, веб-поиска, пользователей и других разделов

`403 SCOPE_DENIED` маршрутов заметок, уведомлений, 1С, публикации страниц, ленты, реквизитов, пользовательских полей, веб-поиска, скрама, задач, пользователей, складов, рабочего дня, бизнес-процессов, рабочих групп, журнала таймлайна, регулярных сделок и CRM-триггеров несёт те же необязательные поля, что и отказы генерируемых маршрутов сущностей: `error.cause` со значением `key_scope_missing`, `error.requiredScope` — недостающий скоуп, `error.keyScopes` — скоупы ключа в этом запросе, `error.fix` — действие, `error.hint` — пояснение на английском и `error.userMessage` — текст для человека, который можно показать как есть. Ответ `GET /v1/search/providers` при этом отказе получил ещё и `success: false`, как все ответы V1 об ошибке. Код, статус и `error.message` не изменились. Разбор — [Авторизация, ключи и права](/docs/errors/auth#scope_denied-403).

### NEW-1001-48: ручки коннекторов для десктопа Коворк

Для десктопа Коворк появились три ручки коннекторов. `GET /v1/connectors` отдаёт коннекторы портала с состоянием для сотрудника и число действий, ждущих подтверждения. `POST /v1/connectors/{slug}/access-requests` подаёт заявку на доступ. `GET /v1/connectors/write-tickets/{id}` отдаёт исход подтверждения записи и текст, с которым агент продолжит работу. Ручки принимают только ключ устройства Коворка, другой ключ получает 403 `CONNECTOR_KEY_NOT_ALLOWED`. Всё работает за флагом коннекторов: пока он выключен, ручки отвечают 404.