Опубликовать приложение в каталоге Битрикс24

POST /v1/infra/servers/:id/b24-catalog/publish

Создаёт карточку приложения в каталоге приложений Вайбкод на портале Битрикс24. До этого вызова карточка появлялась только после успешного деплоя, поэтому приложение, развёрнутое иначе, в каталоге отсутствовало, а выдача доступа сотрудникам его не показывала.

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

Это не публикация REST-приложения и не встройка в интерфейс — для них есть POST /v1/apps/:id/publish и размещения.

Параметры

Тело запроса может быть пустым или {}. Неизвестные поля игнорируются.

Примеры

curl — личный ключ

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{}' \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-catalog/publish

curl — OAuth-приложение

curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" -d '{}' \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-catalog/publish

JavaScript — личный ключ

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/b24-catalog/publish`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: '{}',
  }
)
const body = await res.json()
if (!body.success) {
  // CATALOG_ALREADY_PUBLISHED означает, что карточка уже есть — повторять не нужно
  console.error(body.error.code, body.error.message)
  throw new Error(body.error.code)
}
// Карточка появится в каталоге после ближайшего цикла синхронизации
console.log('Публикация поставлена в очередь')

JavaScript — OAuth-приложение

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/b24-catalog/publish`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: '{}',
  }
)

Поля ответа

Состояние публикации читается через GET /v1/infra/servers/:id в блоке b24CatalogSync:

Значение eligible: true означает «карточка возможна», а не «публикация пройдёт»: у приложения с уже созданной карточкой вызов ответит 409 CATALOG_ALREADY_PUBLISHED.

Пример ответа

{
  "success": true,
  "data": {
    "queued": true,
    "op": "ADD"
  }
}

Пример ответа при ошибке

409 — карточка в каталоге уже есть:

{
  "success": false,
  "error": {
    "code": "CATALOG_ALREADY_PUBLISHED",
    "message": "This server already has a Bitrix24 catalog card."
  }
}

Ошибки

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

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

• Вызов ставит задачу в очередь, а не создаёт карточку. Карточку создаёт фоновая синхронизация, поэтому itemId в GET /v1/infra/servers/:id заполняется не в момент ответа. Отслеживайте готовность опросом: b24CatalogSync.itemId перестал быть null и status стал SYNCED.
• Повторный вызов, пока публикация в очереди, безопасен. Ответ снова 200, вторая карточка не создаётся.
• Управляющий ключ обязателен. Публикация идёт от имени владельца управляющего ключа сервера, поэтому сервер, потерявший ключ, отвечает 400 CATALOG_NOT_ELIGIBLE. Ключ возвращается в личном кабинете.
• Выдача доступа карточку не создаёт. Порядок такой: сначала публикация, затем политика доступа и список доступа. Обратный порядок тоже рабочий — после публикации карточка получит уже выданный доступ на первой же синхронизации.
• Сначала выкладка, потом публикация. Субдомен выдаётся при создании сервера, а приложение появляется на нём только после выкладки, поэтому на сервере без выкладки eligible приходит false, а вызов отвечает 400 CATALOG_NOT_ELIGIBLE. Иначе карточка в каталоге вела бы на адрес, где никто не отвечает, а убрать её можно было бы только удалением сервера. Записи о выкладке платформа не имеет и тогда, когда приложение доставлено не через deploy, а загрузкой файлов, командой или по SSH — такой сервер тоже получает 400 CATALOG_NOT_ELIGIBLE, хотя приложение на нём работает. Обойти это можно только настоящей выкладкой, а она по умолчанию (cleanDeploy) очищает каталог приложения, поэтому сначала сохраните то, что уже разложено.
• Синхронизацию каталога можно выключить на стороне платформы. В этом состоянии eligible приходит false, а вызов публикации отвечает 400 CATALOG_NOT_ELIGIBLE: очередь никто не обработает, поэтому платформа отказывает сразу, а не оставляет карточку «в отправке» бессрочно.

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

• Получить сервер
• Политика доступа
• Список доступа
• Развернуть приложение