#Приложения

OAuth-приложение Вайбкод — это запись в каталоге портала Битрикс24, через которую ваш код встраивается в интерфейс: карточки CRM, левое меню, чаты и другие места встраивания. Жизненный цикл приложения проходит четыре шага: создать → развернуть код → задать адрес → опубликовать. До публикации приложение видит только автор, его адрес appUrl пуст, а список мест встраивания placements пустой — это нормальное состояние, а не ошибка.

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key | Скоуп для публикации: placement

Какой ключ выбрать | Состояния приложения | Полный цикл | Известные особенности | Коды ошибок | Справочник эндпоинтов

#Какой ключ выбрать

Раздел работает с двумя типами ключей.

Личный API-ключ vibe_api_… привязан к одному пользователю и одному порталу Битрикс24 и несёт свой вебхук портала. Запросы идут от лица владельца ключа, заголовок один — X-Api-Key: vibe_api_…, токен сессии не нужен. Этим ключом ведут записи приложений: создают, читают, обновляют и удаляют. Создание — это регистрация настоящего локального OAuth-приложения на портале, и на одном личном ключе таких приложений может быть несколько.

Ключ авторизации vibe_app_… — это ключ самого OAuth-приложения. Чтобы он действовал от лица конкретного пользователя, рядом с X-Api-Key: vibe_app_… нужен заголовок Authorization: Bearer <session_token> — по нему берётся персональный OAuth-токен этого пользователя. Это модель для приложений, которые работают от лица разных пользователей того портала, где приложение зарегистрировано.

Места встраивания и публикация. Запустить публикацию можно любым из ключей, но саму привязку мест встраивания выполняет OAuth-токен приложения — поэтому приложение нужно один раз авторизовать на портале по OAuth, иначе публикация вернёт NO_USER_TOKEN. Приложению, которое открывается внутри портала Битрикс24 от лица пользователя с прозрачной авторизацией, подходит только модель OAuth-приложения vibe_app_… — личного ключа для этого недостаточно.

Сколько приложений можно создать. Число ключей на одного пользователя портала ограничено — по умолчанию 10. Приложения расходуют тот же счётчик, что и личные ключи, отдельного лимита на приложения нет. При достижении лимита создание возвращает 409 KEY_LIMIT_REACHED, а поднимает лимит администратор аккаунта. Подробнее — Сколько ключей можно создать.

Подробное описание типов ключей, форматов и получения session_token — Ключи и авторизация.

#Состояния приложения

Переходы: PRIVATE → PUBLISHED → UNPUBLISHED → PUBLISHED — последняя стрелка это повторная публикация. Снятие с публикации возвращает в UNPUBLISHED, а не в PRIVATE: метаданные каталога сохраняются для повторной публикации.

Статус каталога хранится на стороне платформы и в теле ответа не возвращается. Опубликованное приложение отличает заполненный массив placements, снятое с публикации — пустой.

#Почему `appUrl: null` и пустые `placements` до публикации

Частый вопрос: приложение создано, код развёрнут, GET /v1/me показывает capabilities.apps.publish.available: true, но данные приложения отдают appUrl: null и пустой массив placements, а в каталоге приложения нет. Так и должно быть, пока приложение в статусе PRIVATE:

• appUrl пуст, пока вы не зададите его через обновление приложения или не передадите в теле публикации.
• placements пуст, потому что места встраивания привязываются к порталу только в момент публикации.
• В каталоге приложение появляется только после публикации.

#`appUrl` и `handlerUrl` — разные адреса

handlerUrl платформа задаёт сама, и менять его нельзя — через него идут обратные вызовы OAuth и открытие места встраивания. appUrl — ваш адрес на Black Hole, куда платформа перенаправляет открытие места встраивания. Этот адрес задаёте вы.

#Полный цикл

#Шаг 1. Создать приложение

Создание регистрирует OAuth-приложение на портале и возвращает ключ один раз — в поле rawKey ответа. Сохраните его сразу: повторно ключ не показывается. Для последующей публикации в наборе скоупов обязателен placement.

curl -X POST "https://vibecode.bitrix24.tech/v1/apps" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Дашборд продаж",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech"
  }'

#Шаг 2. Развернуть код и задать адрес

Разверните приложение на Black Hole-сервере (Deploy API) и убедитесь, что appUrl указывает на его адрес. Если адрес не задан при создании — задайте его через обновление:

curl -X PATCH "https://vibecode.bitrix24.tech/v1/apps/APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appUrl": "https://app-abc12345.vibecode.bitrix24.tech" }'

#Шаг 3. Опубликовать

Публикация переводит приложение в PUBLISHED, привязывает места встраивания к порталу и делает приложение видимым всем сотрудникам. Перед публикацией приложение должно быть авторизовано на портале по OAuth, а в наборе скоупов ключа должен быть placement.

curl -X POST "https://vibecode.bitrix24.tech/v1/apps/APP_ID/publish" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "placements": ["CRM_DEAL_DETAIL_TAB"] }'

#Известные особенности

• Приложение привязано к одному порталу. Запись приложения создаётся на портале, чей ключ передан при создании, и работает от лица пользователей этого же портала. Чтобы то же приложение работало на другом портале, зарегистрируйте его там отдельным вызовом `POST /v1/apps` с ключом нужного портала. Тиражируемое приложение — это один код, развёрнутый как отдельная запись на каждом портале.
• Набор скоупов фиксируется при создании. Сменить его у существующего приложения нельзя — чтобы работать с другим набором скоупов, пересоздайте приложение. Без placement в наборе публикация вернёт MISSING_SCOPE, а запрос, которому нужен скоуп вне набора, — BITRIX_ACCESS_DENIED. Подробнее на странице Скоупы.
• Места встраивания со смарт-процессами. Динамические коды вида CRM_DYNAMIC_<entityTypeId>_DETAIL_TAB принимаются наравне со статическими — идентификатор зависит от портала.
• Точный список кодов мест встраивания. placements принимает только коды из фиксированного набора — актуальный перечень отдаёт GET /v1/placements/available. Коды вне набора возвращают 400 VALIDATION_ERROR при привязке. Если нужного кода нет в /available — он не поддерживается.
• appUrl может содержать путь. Допустим не только голый поддомен, но и адрес с путём, например https://app-abc12345.vibecode.bitrix24.tech/hh-connector. Это рабочий приём для нескольких приложений за одним поддоменом Black Hole: разведите их по путям через обратный прокси, а каждому приложению задайте свой appUrl с нужным путём.
• Коннектору открытых линий нужен скоуп imopenlines. Приложению, которое регистрирует коннектор внешнего мессенджера для открытых линий, добавьте в набор скоупов imopenlines. Полный перечень доступных скоупов — на странице Скоупы.

#Коды ошибок

Каждая страница эндпоинта несёт свою таблицу ошибок. Ниже — общие коды, которые возвращает любой эндпоинт раздела.

Полный список общих ошибок API — Ошибки.

#Справочник эндпоинтов

Интерактивный переключатель методов с примерами и полями ответа — Эндпоинты.

#Смотрите также

• Эндпоинты — все методы раздела во вкладках
• Создание ключа — выпуск API-ключа и OAuth-приложения
• Скоупы — какие скоупы нужны под задачу
• Deploy API — развернуть код приложения
• Хранилище исходников — снапшоты исходников и проверка при публикации
• Подписки на события портала — доставка событий Битрикс24 на сервер приложения