Изменения API: 29 августа 2026

← Журнал изменений · Август 2026

FIX-0829-1: признак полей для импорта в guide

Было

В GET /v1/guide подробный контракт data.entities[].fieldsDetailed не сообщал, можно ли задать поле при импорте.

Стало

В data.entities[].fieldsDetailed для таких полей приходит importable: true. Ответ остаётся HTTP 200, компактная карта data.entities[].fields не меняется.

NEW-0829-2: ссылка на публичное приложение разворачивается в карточку

Ссылка на приложение в режиме PUBLIC приходила в мессенджер и в чат Битрикс24 голым адресом субдомена. Сборщик превью получал ту же страницу, что и браузер, и показать ему было нечего.

Ссылка на приложение в режиме PUBLIC разворачивается в карточку с названием, описанием и картинкой. Данные берутся из карточки приложения в каталоге; нет названия в каталоге — подставляется имя сервера, нет иконки — картинка платформы. Собирает карточку сам шлюз: приложение запроса не получает, спящий сервер не просыпается. На любой другой политике доступа карточки нет — сборщик превью получает нейтральную страницу без названия, описания и картинки. Уже показанную карточку отозвать нельзя: принимающая сторона кеширует её у себя, поэтому переключение политики на приватную закрывает только новые запросы. Подробнее — Авторизация в приложении на Black Hole.

BC-0829-3: фильтр лидов учитывает семантику стадии

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

Было

GET /v1/leads, POST /v1/leads/search и POST /v1/leads/aggregate с фильтром stageSemanticId возвращали UNKNOWN_FILTER_FIELD. Поле stageSemanticId, переданное при создании, обновлении, импорте, в пакетном запросе сущности или общем пакетном запросе, игнорировалось.

Стало

Фильтр принимает P (в работе), S (успех) и F (провал). Сортировка по stageSemanticId также доступна. Руководство, OpenAPI и интерактивный справочник описывают поле как строку только для чтения. groupBy: stageSemanticId по-прежнему не поддерживается. Создание и обновление возвращают READONLY_FIELD, импорт — IMPORT_ITEM_VALIDATION, пакетный запрос сущности — BATCH_ITEM_VALIDATION, общий пакетный запрос — READONLY_FIELD для соответствующего вызова.

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

Используйте stageSemanticId только для чтения, фильтрации и сортировки. Удалите поле из тел запросов на создание, обновление и импорт, а также из пакетных запросов. Для группировки выберите другое поле.

FIX-0829-4: списочные вызовы почтовых ящиков и узлов оргструктуры работают в пакетных API

Было

Подвызов {"entity": "mail-mailboxes", "action": "list"} в POST /v1/batch отвечал ошибкой ERROR_METHOD_NOT_FOUND, а тот же список в POST /v1/mail/mailboxes/batch — CALL_FAILED. Так же вёл себя humanresources-nodes. Отдельным запросом GET /v1/mail-mailboxes тот же список отдавал данные.

Стало

Оба пакетных API возвращают записи. Такой подвызов выполняется отдельным запросом к порталу при любом значении limit и расходует свою квоту rate-limit; соседние вызовы других сущностей по-прежнему уезжают одним пакетом. Количество записей у этих двух сущностей приходит всегда, даже с withTotal: false. Действие get у них в пакетном API по-прежнему не отвечает данными — читайте запись её собственным маршрутом. Подробности — в разделе «Известные особенности» страницы «Пакетные операции».

Отдельно изменился текст сообщения у отказавшего подвызова — во всех пакетных вызовах, не только у этих двух сущностей. Раньше туда попадало внутреннее диагностическое сообщение платформы; теперь публикуется только текст, пришедший от Битрикс24, а во всех прочих случаях — фиксированное Internal error. При этом переполнение очереди портала, ожидание в очереди и таймаут портала перестали попадать в общий код и приходят под собственными кодами QUEUE_OVERFLOW, QUEUE_TIMEOUT, BITRIX_TIMEOUT, ERROR_LOOP_DETECTED, RATE_LIMITED, OPERATION_TIME_LIMIT и TOKEN_REFRESH_FAILED, у всех кроме последнего — с полем retryAfter. Их стало можно отличить от внутреннего сбоя. Ответ по-прежнему 200, коды остальных подошибок не менялись.

То же правило действует и когда отказывает пакетный запрос целиком, а не отдельный вызов: текст берётся из ответа Битрикс24, иначе он фиксированный. Статус ответа, код и поле bitrixError при этом не меняются — bitrixError приходит, когда Битрикс24 действительно ответил, даже если текста в его ответе не было.

Одиночные эндпоинты тоже перестали отдавать внутренний текст в одном случае: при отказе TOKEN_REFRESH_FAILED сообщение теперь фиксированное — раньше в него мог попасть кусок ответа портала. Код и статус не изменились.