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

← Журнал изменений · Октябрь 2026

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

Создание и изменение to-do дел CRM доступно через POST /v1/activity-todos и PATCH /v1/activity-todos/:id. Для любого дела добавлены действия: завершить, отложить и перенести срок. Чтение и список дел остаются в /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, документы CRM и шаблоны.

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

Файлы полей CRM доступны через маршрут скачивания, готовые CRM-документы — как DOCX, PDF и изображение. REST-шаблоны тоже скачиваются с ключом API Вайбкод. Принимаются ключи READONLY с нужным скоупом.

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

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

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

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

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

Ответы 413 IMAGE_TOO_LARGE у POST /v1/feedback/attachments и 413 STORAGE_UPLOAD_TOO_LARGE у POST /v1/storage/objects/upload получили необязательное поле 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 Вайбкод

Новые маршруты позволяют получить, создать, изменить и удалить шаблоны 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 не изменились. Разбор — Авторизация, ключи и права.

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 не изменились. Разбор — Авторизация, ключи и права.

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

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

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

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

Было

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

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

Стало

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

Первое и повторное развёртывание сохраняют аудиторию, права доступа и учётные данные. Чтение, доказанное сужение доступа и обновление bearer-токена без тела запроса продолжают работать по существующим правилам авторизации. PATCH /v1/infra/servers/{id}/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}, а также лиды и компании, пакетные вызовы и /v1/batch) Битрикс24 поле id игнорирует и добавляет ВТОРУЮ запись: вызов отвечал 200, а у контакта появлялся дубль телефона. Попытка удалить запись формой { "id": 11, "value": "" } отвечала 200, не делая ничего. На создании (POST /v1/contacts, пакеты, импорт) 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 получил поле 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 под ключом подписки Коворк/Код, выписанным для сторонней агентной программы, называл в блоке deployment эндпоинт POST /v1/cowork/deploy-key с порядком получения ключа деплоя и отдавал поле deployment.deployKeyEndpoint, а примечания слотов серверов и приложений в capabilities советовали тот же эндпоинт. Тот же совет такой ключ получал в error.details.requiredAction отказа 403 INFRA_FORBIDDEN_FOR_COWORK_KEY, а GET /v1/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 с полем, у которого нет точечного метода Битрикс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, GET /v1/infra/servers/:id/sources, POST /v1/files/:id/moveto, POST /v1/files/:id/copyto, POST /v1/folders/:id/moveto, POST /v1/folders/:id/copyto, POST /v1/humanresources/nodes/search, POST /v1/infra/servers/:id/event-subscriptions, GET /v1/note/collections, GET /v1/off-peak, GET /v1/mail/messages, POST /v1/bitrix-handler.

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

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

Было

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

Стало

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

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

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

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

Сервер в режиме «по расписанию» теперь допускается во внешний API приложения ANY /v1/applications/:id/api/**, если его тариф не вытесняемый. Ответ зависит от состояния сервера. Запущенный сервер принимает вызов — в окнах расписания работы и после конца окна, пока он не уснул по простою; такие вызовы продлевают его работу, а это время оплачивает владелец приложения. Спящий сервер вне окна отвечает новым кодом 409 APP_API_OUTSIDE_SCHEDULE с заголовком Retry-After — числом секунд до начала ближайшего окна; повторите вызов после этого срока. Если срок вычислить нельзя (например, расписание сервера удалено), заголовка нет, и повтор по времени не поможет — проверьте расписание сервера. 503 APP_API_UNAVAILABLE получают сервер, пробуждение которого запрещено (например, приостановлено по оплате), и сервер, который не запущен и не спит вне окна: ещё просыпается к началу окна, остановлен, в ошибке или ещё создаётся. Переключатель «Внешний API» у такого сервера включается, пока сервер запущен и его пробуждение не запрещено. Решения на таком сервере подчиняются тому же правилу: пока сервер запущен, публикация контракта решения и вызов решения проходят; к спящему вне окна серверу публикация не проходит, а вызов решения получает SOLUTION_UNAVAILABLE. Серверов без расписания изменение не касается. Подробнее — Внешний 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. См. перенос дела.

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

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

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

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

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 создаёт след посетителя из JSON-объекта или JSON-строки. Можно привязать его к лидам, сделкам, контактам, компаниям и предложениям. Записи проверяются перед добавлением. DELETE /v1/crm-traces/:id отвечает 204 идемпотентно, без подтверждения существования следа или удаления всех привязок. Требуются скоуп crm и ключ READWRITE.

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

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

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 не изменились. Разбор — Авторизация, ключи и права.

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 не изменились. Разбор — Авторизация, ключи и права.

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

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