Изменения API: 2 сентября 2026

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

BC-0902-1: Документы сообщают состояние преобразования в PDF

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

Было

Поля isTransformationError, transformationErrorCode, transformationErrorMessage, transformationCancelReason и pullTag не были объявлены в контракте документов. Если Битрикс24 возвращал их через GET /v1/documents/:id, API Вайбкод передавал значения без нормализации. Те же поля в телах POST /v1/documents и PATCH /v1/documents/:id не отклонялись локальной проверкой полей только для чтения.

Стало

Пять полей объявлены как допускающие null поля ответа только для чтения. isTransformationError возвращается как boolean | null, остальные четыре поля — как string | null. Пустые строки в строковых полях становятся null. Запрос записи с любым из этих полей возвращает 400 READONLY_FIELD.

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

Не передавать эти пять полей в телах создания и изменения документа, в том числе при повторной отправке ранее полученного объекта. При чтении учитывать null и использовать pullTag для подписки на обновления состояния преобразования.

BC-0902-2: Адрес переключателя режима в отказе по режиму доступа больше не фиксирован

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

Было

Отказ по режиму доступа WRITE_BLOCKED_READONLY_KEY всегда возвращал details.switchUrl равным "/keys", а машинная схема закрепляла это значение перечислением enum: ["/keys"]. Раздел ключей показывает только личные ключи, поэтому для двух других видов путь был тупиком: ни ключ авторизации приложения, ни менеджмент-ключ там не показываются по построению — ни владельцу, ни администратору Битрикс24. Держателю сообщали адрес страницы, на которой переключателя для его ключа нет.

Стало

details.switchUrl указывает на страницу, где режим переключается именно у этого ключа: личный ключ — раздел ключей "/keys", ключ авторизации приложения — кабинет приложений "/applications", менеджмент-ключ — раздел менеджмент-ключей "/management-keys". Текст сообщения называет тот же адрес, что и поле, — они собираются вместе и разойтись не могут. Перечисление значений снято со схемы: это путь в интерфейсе, а не константа протокола, и закрепление литерала делало контракт невыполнимым при переезде страницы. Поле по-прежнему приходит всегда и остаётся обязательным — изменилось значение, а не наличие.

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

Читать switchUrl из ответа, а не подставлять "/keys". Клиентам, которые генерируют типы из схемы, литеральный тип '/keys' больше не выдаётся — обновите сгенерированные типы, иначе проверка значения не пройдёт.

FIX-0902-3: поток, который не начался, завершается повторяемой ошибкой у моделей всех поставщиков

Было

У моделей bitrix/* установка потока уже делала одну попытку с общим бюджетом, а у моделей остальных поставщиков платформа молча отправляла запрос второй раз и ждала ещё один полный бюджет. Клиент в это время не получал ничего — до двух полных бюджетов тишины, — а затем видел общий отказ провайдера, по которому нельзя отличить зависшую установку потока от любой другой неопознанной ошибки.

data: { "error": { "code": "ai_provider_unavailable", "type": "server_error", "retryable": true, "retryAfter": 6 } }
data: [DONE]

Стало

Установка потока делает одну попытку с общим бюджетом у моделей ЛЮБОГО поставщика. Если заголовки не пришли за отведённое время, ожидание не удваивается, а поток завершается тем же событием stream_idle_timeout, что и замолчавший в середине ответа, — по нему видно, что молчал именно поток.

data: { "error": { "code": "stream_idle_timeout", "type": "server_error", "retryable": true, "retryAfter": 7 } }
data: [DONE]

Ожидание больше не удваивается невидимо, а причина отказа названа точно — теперь на всём наборе моделей, а не только на bitrix/*.

NEW-0902-4: список ресурсов бронирования в V1

Появился GET /v1/booking-resources — он возвращает ресурсы бронирования, доступные ключу, и закрывает разрыв в сценарии первого бронирования: POST /v1/bookings требует непустой resourceIds, а узнать валидные идентификаторы средствами одного только V1 было нельзя.

Нужен скоуп booking. Ключ с режимом «только чтение» подходит — метод читающий. Фильтры typeId и searchQuery необязательны и комбинируются, любой другой параметр отклоняется с 400 INVALID_PARAMS.

Каталог собирается целиком, поэтому параметров постраничного вывода нет: meta.total равен длине data, meta.hasMore всегда false. Каждая запись несёт ровно четыре поля — id, name, typeId и isMain. Поле description не отдаётся: это свободный текст портала, для выбора ресурса он не нужен.

Полнота ответа гарантируется для каталога, не менявшегося во время запроса, — снимка коллекции Битрикс24 не предоставляет. Портал больше чем с 500 ресурсами получает 502 BITRIX_RESULT_TOO_LARGE вместо усечённого списка; сузить выборку помогают те же два фильтра.

NEW-0902-6: device-flow принимает идентификатор устройства

POST /v1/connect/device/authorize принимает необязательный параметр device_id — стабильный идентификатор установки клиента (до 128 символов, буквы, цифры, _.:-). Он действует для приложения Cowork/Code: при повторном подключении с того же устройства прежний ключ отзывается, а не остаётся в списке рядом с новым. Сторонние клиенты параметр передавать могут, но на выдачу их ключей он пока не влияет.

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

NEW-0902-7: новый код отказа INT_BOX_PARTNER_REQUIRED для коробок на международной установке

На международной установке доступ коробочного портала к платформе может требовать подтверждённой партнёрской (NFR) лицензии. Коробка без подтверждения получает HTTP 402 с новым кодом INT_BOX_PARTNER_REQUIRED — на создании сервера, агента, управляемого бота и на выписке ключа. Тело отказа устроено как у соседних кодов этого семейства (userMessage, alternatives, hint), но поле details.requiredTariffs пустое: переход на другой тариф Битрикс24 этот отказ не снимает, признак читается при регистрации модуля коннектора. Тот же код приезжает в поле reason слота capabilities.servers.create ответа GET /v1/me, а адрес документации — в его alternatives[].url. Требование включается отдельно; пока оно не включено, ни один портал этого кода не увидит и ответы остаются прежними.

NEW-0902-8: стабильный идентификатор портала в самоописании ключа

GET /v1/me возвращает новое поле portalId — устойчивый идентификатор портала Битрикс24, к которому привязан ключ. Оно приходит тем же запросом, рядом с уже существующими portal и owner, и есть у ключей vibe_api_ и vibe_app_.

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

В успешном ответе поле всегда непустое: ключ без привязанного портала до этого ответа не доходит, он получает 401 NO_PORTAL. Менеджмент-ключи vibe_live_ нового поля не получают — они не привязаны к одному порталу и по-прежнему отдают перечень порталов в portals.

NEW-0902-9: создание сервера отвечает 409 `REISSUE_IN_PROGRESS`, пока перевыпускается ключ авторизации приложения

У POST /v1/infra/servers появился новый код отказа REISSUE_IN_PROGRESS со статусом 409. Платформа Вайбкод отвечает им, когда владелец карточки приложения в этот момент перевыпускает её ключ авторизации: сервер не создаётся, потому что он оказался бы на ключе, который отзывается в ту же секунду.

Отказ временный — повторите запрос после того, как перевыпуск завершится. Успешный ответ и все прочие коды отказа прежние, запросы, которые работали раньше, работают без изменений.

FIX-0902-10: методы дашборда Открытых линий появились в OpenAPI

Было

Шесть публичных методов статистики Открытых линий были описаны на страницах документации, но отсутствовали в /v1/openapi.json и сгенерированных карточках API.

Стало

Все шесть методов доступны в OpenAPI и карточках API со скоупом imopenlines, параметрами и форматами ответов. Runtime-поведение не менялось: успешный ответ остаётся HTTP 200, прежние статусы и форматы ошибок сохранены.

NEW-0902-11: код обращения в неопознанном отказе выписки ключа

Когда Битрикс24 отказывает в выписке ключа причиной, которую платформа не распознаёт, ответ теперь дополнительно несёт error.details.incidentCode — код обращения из шести символов (латинские буквы и цифры). Тот же код платформа записывает в журнал портала рядом с разбором отказа, поэтому поддержке достаточно его назвать, чтобы найти запись.

Поле опциональное и добавлено к уже существующему телу ответа: HTTP-статус, error.code и error.details.reason прежние, клиентам делать ничего не нужно.

NEW-0902-12: лимит частоты, ETag и Vary у GET /v1/openapi.json

У GET /v1/openapi.json появился лимит частоты на один адрес вызывающего. Точное значение потолка отдаётся в заголовке x-ratelimit-limit ответа — читайте его оттуда, а не задавайте числом в коде. Превышение отвечает 429 RATE_LIMITED. Лимит щедрый и на обычное чтение не рассчитан: спека отдаётся с ETag, поэтому дискавери-клиент и генератор SDK повторно получают 304 вместо тела.

Тело спеки может зависеть от ключа в запросе. Поэтому ответ помечен Vary: Authorization, X-Api-Key (ключ читается из любого из двух заголовков), а с ключом, для которого тело отличается, отдаётся под Cache-Control: private вместо public. Не переиспользуйте один сохранённый файл спеки между разными ключами.

FIX-0902-13: тарифный отказ Битрикс24 при выписке ключа и установке приложения называет причину

Было

Когда Битрикс24 отказывал в выписке кодом FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN (тариф портала не включает Вайбкод), ответ был безликим на ЛЮБОЙ ручке выписки — и там, где выпускается ключ (POST /v1/keys → 502 CONNECTOR_KEY_ISSUE_FAILED), и там, где устанавливается приложение (POST /v1/apps → 502 CONNECTOR_APP_INSTALL_FAILED). Текста для человека в теле не было вовсе, а причина оставалась только во внутреннем поле, поэтому клиент читал отказ как временный сбой платформы и повторял запрос. Повтор не помогает никогда: гейт снимается только сменой тарифа Битрикс24.

HTTP 502
{ "success": false, "error": { "code": "CONNECTOR_KEY_ISSUE_FAILED", "message": "connector refused to issue the key" } }

Стало

Отказ разбирается по региону портала. Там, где доступ продаётся, приходит 402 с кодом тарифного пейвола и текстом для человека: на международном сегменте — INT_VIBE_PLUS_REQUIRED с details.requiredTariffs: ["vibe+"] и details.upgradeUrl на страницу подключения тарифа в самом портале, в тарифных регионах СНГ на бесплатном тарифе — BY_PAID_ONLY, KZ_PAID_ONLY или UZ_PAID_ONLY. Там, где предлагать нечего (коробочный портал, портал уже на платном тарифе, нераспознанный регион), ответ остаётся 502, но получает собственный код CONNECTOR_PLAN_REQUIRED и непустой userMessage вместо пустого тела.

HTTP 402
{ "success": false, "error": { "code": "INT_VIBE_PLUS_REQUIRED", "message": "This action requires a Vibe+ plan on your Bitrix24 account.", "details": { "requiredTariffs": ["vibe+"], "upgradeUrl": "https://example.bitrix24.com/online/?feature_promoter=limit_why_pay_tariff_vibe" } } }

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

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

FIX-0902-14: отказ на странице согласия возвращает пользователя в приложение партнёра

Было

Пользователь подтверждал доступ, упирался в отказ выдачи ключа — нет подписки, неподдерживаемый регион, исчерпан лимит ключей — и оставался на странице согласия. На redirect_uri не уходило ничего: партнёр не узнавал ни о попытке, ни о её причине.

Стало

Отказ несёт готовый адрес возврата: на странице появляется кнопка «Вернуться в приложение», а redirect_uri получает error=access_denied (temporarily_unavailable при недоступности Битрикс24), машинный код причины в error_description и исходный state. Если у зарегистрированного адреса возврата был свой параметр code, при отказе он снимается — отказ не приходит вперемешку с признаками успеха. Так же ведут себя отказы до подтверждения — протухшая ссылка согласия и битый CSRF-токен, в том числе на кнопке «Отклонить».