#Приложения: создание и публикация

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

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

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

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

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

• appUrl пуст, пока вы не зададите его явно через PATCH /v1/apps/:id или не передадите в теле публикации;
• placements пуст, потому что места встраивания привязываются к порталу только в момент публикации;
• в каталоге приложение появляется только после POST /v1/apps/:id/publish.

#Полный цикл

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

POST /v1/apps регистрирует 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. Опубликовать

POST /v1/apps/:id/publish переводит приложение в PUBLISHED, привязывает места встраивания к порталу и делает приложение видимым всем сотрудникам.

#Публикация

POST /v1/apps/:id/publish

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

#Примеры

# Минимальная публикация — все параметры берутся из записи приложения
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 '{}'

# Публикация с явными местами встраивания и заголовком
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 '{
    "catalogTitle": "Дашборд продаж",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech",
    "placements": ["CRM_DEAL_DETAIL_TAB", "LEFT_MENU"]
  }'

const res = await fetch('https://vibecode.bitrix24.tech/v1/apps/APP_ID/publish', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    placements: ['CRM_DEAL_DETAIL_TAB'],
  }),
})

const { success, data } = await res.json()
if (success) console.log('Опубликовано, места встраивания:', data.placements)

#Поля ответа

В ответе возвращается обновлённая запись приложения. Успешная публикация подтверждается success: true и заполненным массивом data.placements (плюс data.appUrl). Отдельного поля статуса каталога в ответе нет.

{
  "success": true,
  "data": {
    "id": "APP_ID",
    "title": "Дашборд продаж",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech",
    "placements": ["CRM_DEAL_DETAIL_TAB"]
  }
}

#Снятие с публикации

POST /v1/apps/:id/unpublish

Отвязывает места встраивания от портала и переводит приложение в UNPUBLISHED. Тело не требуется. Метаданные каталога сохраняются — повторная публикация вернёт приложение в каталог.

curl -X POST "https://vibecode.bitrix24.tech/v1/apps/APP_ID/unpublish" \
  -H "X-Api-Key: YOUR_API_KEY"

#Ошибки

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

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

• Привязка мест встраивания требует коммерческого тарифа Битрикс24. Создание приложения, чтение мест встраивания и снятие с публикации работают на любом тарифе. Сама привязка (а значит и публикация, которая её выполняет) на бесплатном тарифе вернёт 502 BITRIX_UNAVAILABLE — это ограничение на стороне Битрикс24, не платформы. GET /v1/me отражает это в capabilities.apps.bindPlacements.
• appUrl и handlerUrl — разные адреса. handlerUrl платформа задаёт сама и менять его нельзя — через него идут OAuth-колбэки и открытие iframe. appUrl — ваш адрес на Black Hole, куда платформа перенаправляет открытие места встраивания; его задаёте вы.
• Скоуп placement нельзя добавить задним числом. Набор скоупов Битрикс24 закрепляется за ключом при создании. Если приложение создано без placement, публикация вернёт MISSING_SCOPE — пересоздайте приложение с нужным скоупом (см. Скоупы).
• Смена скоупов не применяется к уже установленному приложению автоматически. Если изменить набор скоупов Битрикс24 у опубликованного приложения, уже выданный токен продолжит обращаться к данным со старым набором — новые скоупы вступят в силу только после переустановки (повторной авторизации) приложения на портале. До переустановки запросы, которым нужен добавленный скоуп, возвращают BITRIX_ACCESS_DENIED. То же правило для API-ключей описано на странице Скоупы.
• Места встраивания со смарт-процессами. Динамические коды вида CRM_DYNAMIC_<entityTypeId>_DETAIL_TAB принимаются наравне со статическими — id зависит от портала.
• Точный список кодов мест встраивания. placements принимает только коды из фиксированного набора — актуальный перечень отдаёт GET /v1/placements/available. Коды вне набора (например, CONTACT_CENTER) возвращают 400 VALIDATION_ERROR при POST /v1/placements/bind. Если нужного кода нет в /available — он не поддерживается, угадывать имя бесполезно.
• appUrl может содержать путь. Допустим не только голый поддомен, но и адрес с путём (https://app-abc12345.vibecode.bitrix24.tech/hh-connector) — PATCH /v1/apps/:id его принимает. Это рабочий приём для нескольких приложений за одним поддоменом Black Hole: разведите их по путям через обратный прокси на своём сервере, а каждому приложению задайте свой appUrl с нужным путём.
• Методы коннекторов внешних мессенджеров — под скоупом imopenlines. Регистрация коннектора открытых линий (imconnector.*) исполняется Битрикс24 под скоупом imopenlines — указывайте его для этих методов. Полный перечень доступных скоупов — Скоупы.

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

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