Изменения API: 1 июля 2026

← Журнал изменений · Июль 2026

FIX-0701-1: Загрузка файла на Диск принимает файлы больше 1 МБ

Было

POST /v1/files/upload отклонял тело запроса больше ~1 МБ ошибкой FST_ERR_CTP_BODY_TOO_LARGE. Файл передаётся в base64 в JSON-теле, а base64 раздувает размер примерно на треть — поэтому даже файл 1,1 МБ не проходил. Способа загрузить файл крупнее не было.

Стало

Лимит тела этого маршрута поднят до 70 МБ — этого хватает на файл около 50 МБ с учётом base64 и JSON-обёртки (запись звонка, типовые вложения). Битрикс24 по-прежнему применяет собственное ограничение на размер файла Диска: при его превышении ошибка приходит в стандартном конверте. Для файлов в сотни МБ нужен отдельный способ загрузки (multipart / presigned) — он пока не реализован.

NEW-0701-2: иконка приложения сервера: загрузка SVG, анонимная отдача, фавикон

Появился способ задать иконку приложения для сервера. POST /v1/infra/servers/:id/icon (multipart/form-data, поле file, только SVG до 256 КБ, без скриптов, обработчиков событий и внешних ссылок) загружает иконку; она отдаётся анонимно по стабильному GET /api/server-icons/:id и показывается в каталоге приложений Bitrix24. Чтобы иконка стала фавиконом во вкладке браузера, впишите <link rel="icon" type="image/svg+xml" href="<базовый-URL>/api/server-icons/:id"> в HTML приложения во время сборки — после этого перезаливка иконки обновляет каталог и фавикон автоматически. Формат, требования и порядок — Иконка приложения.

NEW-0701-3: Профиль текущего пользователя сообщает права администратора

Ответ GET /v1/users/me теперь возвращает рабочее поле isAdmin: true — пользователь администратор портала, false — нет, null — определить не удалось (временный сбой; профиль при этом всё равно возвращается). Поле пригодно для серверной проверки прав в вашем бэкенде. На GET /v1/users/:id и в списке пользователей поле по-прежнему недоступно — вердикт отдаётся только для текущего пользователя сессии.

NEW-0701-4: Расширенный статический контракт полей в /v1/guide и указатель schema-discovery в /v1/me

По каждой сущности в ответе GET /v1/guide добавлено поле data.entities[].fieldsDetailed — расширенный статический контракт полей: type, readonly, required, createOnly и декодирование enum (например, значения status и priority у задач). Оно доступно по одному заголовку X-Api-Key, без сессии, и предназначено для маппингов и кодогенерации до появления пользовательской сессии. Компактное поле fields сохранено без изменений.

Ответ GET /v1/me для ключа авторизации без пользовательской сессии (без заголовка Authorization: Bearer) теперь содержит блок schemaDiscovery — указатель, где брать статическую схему без сессии (/v1/guide) и как получить живые и пользовательские поля (Bearer-сессия или персональный ключ). Эндпоинты GET /v1/<entity>/fields и GET /v1/userfields/* не изменились.

BC-0701-5: categoryId в ответе постов теперь массив чисел

Поддержка старого формата до: 01.01.2027

Было

GET /v1/posts отдавал categoryId с типом, зависящим от количества категорий поста: null без категорий, число (11) для одной, строка со списком ID через запятую ("5,7,9") для нескольких. Типизированный клиент с полем categoryId: number | null работал на постах с одной категорией, но ломался на постах с двумя и более.

Стало

categoryId — всегда массив чисел number[]: [] без категорий, [11] для одной, [5, 7, 9] для нескольких. Тип единый независимо от количества категорий.

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

Читайте categoryId как массив: post.categoryId.length вместо проверки на null, post.categoryId[0] для первой категории. Прежнюю ветку «число или строка» можно убрать.

FIX-0701-6: единые коды ошибок токена и скоупа в разделе Диска

Было

Пользовательские операции Диска — POST /v1/files/:id/moveto, copyto, POST /v1/files/upload, GET /v1/files/:id/download и аналоги для папок — при отсутствии токенов портала возвращали 401 NO_TOKENS, а при нехватке скоупа disk — 403 SCOPE_MISSING. Сгенерированные CRUD-операции того же раздела (list/get/create/update/delete) для тех же условий уже возвращали 401 TOKEN_MISSING и 403 SCOPE_DENIED — поэтому в пределах одного раздела клиент видел два разных кода для одной ошибки.

Стало

Все операции Диска возвращают единые коды — 401 TOKEN_MISSING и 403 SCOPE_DENIED, как и остальной V1 API. HTTP-статусы (401 и 403) не изменились.

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

Если код ветвился по строкам NO_TOKENS или SCOPE_MISSING на операциях moveto/copyto/upload/download, переключитесь на TOKEN_MISSING / SCOPE_DENIED (или проверяйте HTTP-статус). Остальным менять ничего не нужно.

FIX-0701-7: placement CALL_CARD убран из списка допустимых

Было

Код placement CALL_CARD числился допустимым: POST /v1/placements/bind пропускал его через валидацию и передавал в Битрикс24, а GET /v1/placements/available выдавал его в списке. Но ни один модуль Битрикс24 не регистрирует этот placement, поэтому placement.bind завершался внутренней ошибкой, которую платформа отдавала как INTERNAL_SERVER_ERROR.

Стало

CALL_CARD удалён из списка допустимых: он больше не появляется в GET /v1/placements/available, а POST /v1/placements/bind с ним отклоняется сразу понятной ошибкой VALIDATION_ERROR, без обращения к Битрикс24.

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

Привязка CALL_CARD не работала и раньше (возвращала непонятную ошибку 500), поэтому рабочих интеграций изменение не ломает. Для панели приложений в карточке звонка используйте актуальные placement'ы из GET /v1/placements/available.

FIX-0701-8: workday open/close/pause: поле userId теперь применяется

Было

Документированное поле тела userId в POST /v1/workday/open, POST /v1/workday/close и POST /v1/workday/pause молча игнорировалось: операция всегда выполнялась над владельцем токенов ключа, даже если был передан другой сотрудник. Ответ приходил success, но действие затрагивало не того пользователя.

Стало

userId транслируется в параметр Битрикс24 USER_ID, поэтому операция выполняется над указанным сотрудником (при наличии прав администратора или руководителя). Несуществующий userId теперь возвращает ошибку Битрикс24, а не мнимый успех. Некорректный userId (не положительное целое) отклоняется как 400 INVALID_PARAMS. Поведение совпадает с уже работавшим GET /v1/workday/status.

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

Кто не передавал userId, изменений не заметит — операция по-прежнему применяется к владельцу токенов. Кто передавал userId, теперь получит корректное действие над указанным сотрудником.