[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-apps":3,"docs-tabs-apps":6},{"content":4,"lastmod":5},"\n# Приложения\n\nOAuth-приложение Вайбкод — это запись в каталоге портала Битрикс24, через которую ваш код встраивается в интерфейс: карточки CRM, левое меню, чаты и другие места встраивания. Жизненный цикл приложения проходит четыре шага: создать → развернуть код → задать адрес → опубликовать. До публикации приложение видит только автор, его адрес `appUrl` пуст, а список мест встраивания `placements` пустой — это нормальное состояние, а не ошибка.\n\n**Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` | **Авторизация:** `X-Api-Key` | **Скоуп для публикации:** `placement`\n\n[Какой ключ выбрать](#какой-ключ-выбрать) | [Состояния приложения](#состояния-приложения) | [Полный цикл](#полный-цикл) | [Известные особенности](#известные-особенности) | [Коды ошибок](#коды-ошибок) | [Справочник эндпоинтов](#справочник-эндпоинтов)\n\n## Какой ключ выбрать\n\nРаздел работает с двумя типами ключей.\n\n**Личный API-ключ `vibe_api_…`** привязан к одному пользователю и одному порталу Битрикс24 и несёт свой вебхук портала. Запросы идут от лица владельца ключа, заголовок один — `X-Api-Key: vibe_api_…`, токен сессии не нужен. Этим ключом ведут записи приложений: создают, читают, обновляют и удаляют. Создание — это регистрация настоящего локального OAuth-приложения на портале, и на одном личном ключе таких приложений может быть несколько.\n\n**Ключ авторизации `vibe_app_…`** — это ключ самого OAuth-приложения. Чтобы он действовал от лица конкретного пользователя, рядом с `X-Api-Key: vibe_app_…` нужен заголовок `Authorization: Bearer \u003Csession_token>` — по нему берётся персональный OAuth-токен этого пользователя. Это модель для приложений, которые работают от лица разных пользователей того портала, где приложение зарегистрировано.\n\n**Места встраивания и публикация.** Запустить публикацию можно любым из ключей, но саму привязку мест встраивания выполняет OAuth-токен приложения — поэтому приложение нужно один раз авторизовать на портале по OAuth, иначе публикация вернёт `NO_USER_TOKEN`. Приложению, которое открывается внутри портала Битрикс24 от лица пользователя с прозрачной авторизацией, подходит только модель OAuth-приложения `vibe_app_…` — личного ключа для этого недостаточно.\n\n**Сколько приложений можно создать.** Число ключей на одного пользователя портала ограничено — по умолчанию 10. Приложения расходуют тот же счётчик, что и личные ключи, отдельного лимита на приложения нет. При достижении лимита создание возвращает `409 KEY_LIMIT_REACHED`, а поднимает лимит администратор аккаунта. Подробнее — [Сколько ключей можно создать](\u002Fdocs\u002Fkeys-auth#сколько-ключей-можно-создать).\n\nПодробное описание типов ключей, форматов и получения `session_token` — [Ключи и авторизация](\u002Fdocs\u002Fkeys-auth).\n\n---\n\n## Состояния приложения\n\n| Статус | Что значит | Видно в каталоге |\n|--------|------------|------------------|\n| `PRIVATE` | Состояние по умолчанию сразу после создания. Места встраивания не привязаны к порталу | Только автору |\n| `PUBLISHED` | Приложение опубликовано, места встраивания привязаны к порталу | Всем сотрудникам портала |\n| `UNPUBLISHED` | Снято с публикации, места встраивания отвязаны, но карточка в каталоге сохранена | Всем, неактивно |\n\nПереходы: `PRIVATE → PUBLISHED → UNPUBLISHED → PUBLISHED` — последняя стрелка это повторная публикация. Снятие с публикации возвращает в `UNPUBLISHED`, а не в `PRIVATE`: метаданные каталога сохраняются для повторной публикации.\n\nСтатус каталога хранится на стороне платформы и в теле ответа не возвращается. Опубликованное приложение отличает заполненный массив `placements`, снятое с публикации — пустой.\n\n### Почему `appUrl: null` и пустые `placements` до публикации\n\nЧастый вопрос: приложение создано, код развёрнут, `GET \u002Fv1\u002Fme` показывает `capabilities.apps.publish.available: true`, но [данные приложения](\u002Fdocs\u002Fapps\u002Fget) отдают `appUrl: null` и пустой массив `placements`, а в каталоге приложения нет. Так и должно быть, пока приложение в статусе `PRIVATE`:\n\n- `appUrl` пуст, пока вы не зададите его через [обновление приложения](\u002Fdocs\u002Fapps\u002Fupdate) или не передадите в теле публикации.\n- `placements` пуст, потому что места встраивания привязываются к порталу только в момент публикации.\n- В каталоге приложение появляется только после [публикации](\u002Fdocs\u002Fapps\u002Fpublish).\n\n### `appUrl` и `handlerUrl` — разные адреса\n\n`handlerUrl` платформа задаёт сама, и менять его нельзя — через него идут обратные вызовы OAuth и открытие места встраивания. `appUrl` — ваш адрес на Black Hole, куда платформа перенаправляет открытие места встраивания. Этот адрес задаёте вы.\n\n---\n\n## Полный цикл\n\n### Шаг 1. Создать приложение\n\n[Создание](\u002Fdocs\u002Fapps\u002Fcreate) регистрирует OAuth-приложение на портале и возвращает ключ **один раз** — в поле `rawKey` ответа. Сохраните его сразу: повторно ключ не показывается. Для последующей публикации в наборе скоупов **обязателен** `placement`.\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fapps\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"title\": \"Дашборд продаж\",\n    \"scopes\": [\"crm\", \"user\", \"placement\"],\n    \"appUrl\": \"https:\u002F\u002Fapp-abc12345.vibecode.bitrix24.tech\"\n  }'\n```\n\n### Шаг 2. Развернуть код и задать адрес\n\nРазверните приложение на Black Hole-сервере ([Deploy API](\u002Fdocs\u002Finfra\u002Fdeploy\u002Fdeploy)) и убедитесь, что `appUrl` указывает на его адрес. Если адрес не задан при создании — задайте его через [обновление](\u002Fdocs\u002Fapps\u002Fupdate):\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fapps\u002FAPP_ID\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"appUrl\": \"https:\u002F\u002Fapp-abc12345.vibecode.bitrix24.tech\" }'\n```\n\n### Шаг 3. Опубликовать\n\n[Публикация](\u002Fdocs\u002Fapps\u002Fpublish) переводит приложение в `PUBLISHED`, привязывает места встраивания к порталу и делает приложение видимым всем сотрудникам. Перед публикацией приложение должно быть авторизовано на портале по OAuth, а в наборе скоупов ключа должен быть `placement`.\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fapps\u002FAPP_ID\u002Fpublish\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"placements\": [\"CRM_DEAL_DETAIL_TAB\"] }'\n```\n\n---\n\n## Известные особенности\n\n- **Приложение привязано к одному порталу.** Запись приложения создаётся на портале, чей ключ передан при [создании](\u002Fdocs\u002Fapps\u002Fcreate), и работает от лица пользователей этого же портала. Чтобы то же приложение работало на другом портале, зарегистрируйте его там отдельным вызовом [`POST \u002Fv1\u002Fapps`](\u002Fdocs\u002Fapps\u002Fcreate) с ключом нужного портала. Тиражируемое приложение — это один код, развёрнутый как отдельная запись на каждом портале.\n- **Набор скоупов фиксируется при создании.** Сменить его у существующего приложения нельзя — чтобы работать с другим набором скоупов, пересоздайте приложение. Без `placement` в наборе публикация вернёт `MISSING_SCOPE`, а запрос, которому нужен скоуп вне набора, — `BITRIX_ACCESS_DENIED`. Подробнее на странице [Скоупы](\u002Fdocs\u002Fscopes).\n- **Места встраивания со смарт-процессами.** Динамические коды вида `CRM_DYNAMIC_\u003CentityTypeId>_DETAIL_TAB` принимаются наравне со статическими — идентификатор зависит от портала.\n- **Точный список кодов мест встраивания.** `placements` принимает только коды из фиксированного набора — актуальный перечень отдаёт `GET \u002Fv1\u002Fplacements\u002Favailable`. Коды вне набора возвращают `400 VALIDATION_ERROR` при привязке. Если нужного кода нет в `\u002Favailable` — он не поддерживается.\n- **`appUrl` может содержать путь.** Допустим не только голый поддомен, но и адрес с путём, например `https:\u002F\u002Fapp-abc12345.vibecode.bitrix24.tech\u002Fhh-connector`. Это рабочий приём для нескольких приложений за одним поддоменом Black Hole: разведите их по путям через обратный прокси, а каждому приложению задайте свой `appUrl` с нужным путём.\n- **Коннектору открытых линий нужен скоуп `imopenlines`.** Приложению, которое регистрирует коннектор внешнего мессенджера для открытых линий, добавьте в набор скоупов `imopenlines`. Полный перечень доступных скоупов — на странице [Скоупы](\u002Fdocs\u002Fscopes).\n\n---\n\n## Коды ошибок\n\nКаждая страница эндпоинта несёт свою таблицу ошибок. Ниже — общие коды, которые возвращает любой эндпоинт раздела.\n\n| Код | HTTP | Описание |\n|-----|------|----------|\n| `MISSING_API_KEY` | 401 | Отсутствует заголовок `X-Api-Key` |\n| `INVALID_API_KEY` | 401 | Неверный API-ключ |\n| `RATE_LIMITED` | 429 | Превышен лимит запросов |\n| `BITRIX_UNAVAILABLE` | 502 | Портал Битрикс24 недоступен |\n| `INTERNAL_ERROR` | 500 | Внутренняя ошибка сервера |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n---\n\n## Справочник эндпоинтов\n\n| Метод | Путь | Описание |\n|-------|------|----------|\n| GET | [\u002Fv1\u002Fapps](\u002Fdocs\u002Fapps\u002Flist) | Список приложений портала |\n| POST | [\u002Fv1\u002Fapps](\u002Fdocs\u002Fapps\u002Fcreate) | Создать приложение |\n| GET | [\u002Fv1\u002Fapps\u002F:id](\u002Fdocs\u002Fapps\u002Fget) | Данные приложения |\n| PATCH | [\u002Fv1\u002Fapps\u002F:id](\u002Fdocs\u002Fapps\u002Fupdate) | Обновить приложение |\n| DELETE | [\u002Fv1\u002Fapps\u002F:id](\u002Fdocs\u002Fapps\u002Fdelete) | Удалить приложение |\n| POST | [\u002Fv1\u002Fapps\u002F:id\u002Fpublish](\u002Fdocs\u002Fapps\u002Fpublish) | Опубликовать в каталоге |\n| POST | [\u002Fv1\u002Fapps\u002F:id\u002Funpublish](\u002Fdocs\u002Fapps\u002Funpublish) | Снять с публикации |\n\nИнтерактивный переключатель методов с примерами и полями ответа — [Эндпоинты](\u002Fdocs\u002Fapps\u002Fendpoints).\n\n## Смотрите также\n\n- [Эндпоинты](\u002Fdocs\u002Fapps\u002Fendpoints) — все методы раздела во вкладках\n- [Создание ключа](\u002Fdocs\u002Fkeys-auth) — выпуск API-ключа и OAuth-приложения\n- [Скоупы](\u002Fdocs\u002Fscopes) — какие скоупы нужны под задачу\n- [Deploy API](\u002Fdocs\u002Finfra\u002Fdeploy\u002Fdeploy) — развернуть код приложения\n- [Хранилище исходников](\u002Fdocs\u002Fsource-storage) — снапшоты исходников и проверка при публикации\n- [Подписки на события портала](\u002Fdocs\u002Finfra\u002Fevent-subscriptions) — доставка событий Битрикс24 на сервер приложения\n","2026-07-07",{}]