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

[← Журнал изменений](/docs/changelog) · [Август 2026](/docs/changelog/2026-08)

### 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](/docs/infra/app-runtime).

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

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

**Было**

[GET /v1/leads](/docs/entities/leads/list), [POST /v1/leads/search](/docs/entities/leads/search) и [POST /v1/leads/aggregate](/docs/entities/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` сообщение теперь фиксированное — раньше в него мог
попасть кусок ответа портала. Код и статус не изменились.