Чертежи приложений

Библиотека готовых технических заданий (ТЗ) для популярных приложений Битрикс24 — дашборды, AI-боты, калькуляторы. Пользователь выбирает чертёж в кабинете Вайбкод и копирует промт для своего AI-агента. Промт несёт ссылку на сырой markdown ТЗ по этому эндпоинту — агент скачивает ТЗ тем же API-ключом и строит приложение по нему. Раздел содержит один эндпоинт — получение ТЗ чертежа.

Скоуп: не требуется — работает с любым портал-привязанным ключом (личным или OAuth-приложения) · Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: заголовок X-Api-Key

Доступность чертежей

Чертежи открываются порталам по очереди, и включает их команда Вайбкод — на стороне портала такой настройки нет. Признак, что раздел ещё не открыт: в кабинете нет пункта «Чертежи приложений», а запрос ТЗ отвечает 403 с кодом BLUEPRINTS_DISABLED. Чтобы открыть раздел, обратитесь в поддержку.

Как это работает

1. Пользователь открывает раздел «Чертежи приложений» в кабинете Вайбкод (/blueprints) или выбирает чертёж в диалоге создания ключа.
2. Копирует промт для AI — тот содержит имя приложения и ссылку вида GET /v1/app/blueprints/:slug (с параметром locale), размеченную под ключ пользователя.
3. AI-агент (Claude Code, Cursor и подобные) выполняет запрос своим API-ключом и получает сырой markdown ТЗ — дальше строит приложение по этому тексту.

Список доступных slug не публикуется отдельным эндпоинтом V1 — агенту достаточно ссылки из скопированного промта, готовить slug заранее не нужно.

Оформление нового приложения

До выбора оформления агент читает полный успешный ответ GET /v1/me ключом приложения и применяет data.uiDesign с policyVersion=2. При работе через MCP нужен полный get_me({}) без sections, где блок называется uiDesign. Чертёж содержит указатель на этот источник, а не собственную таблицу правил или палитру.

Стандартный запрос на новое приложение без указанного места при подтверждённой привязке portal_bound выбирает для первой версии светлый дизайн Битрикс24 без вопроса о месте или бренде. Это умолчание оформления, а не выбор iframe или placement-архитектуры. Явная внешняя страница требует уточнить бренд и способ его применения, а пожелание пользователя об оформлении имеет приоритет. При unresolved, в том числе с управляющим ключом, выберите аккаунт и прочитайте ответ его APP-ключом либо уточните назначение. Привязка определяет контекст дизайна, но не доказывает iframe и не даёт прав на создание, встраивание или публикацию.

Если запрос не удался, блок отсутствует или версия политики не поддерживается, агент сообщает, что правило не прочитано, и уточняет оформление. Существующий интерфейс сохраняет дизайн. Фоновые процессы, сообщения бота и создаваемый документ не получают оформление страницы: экран настроек или панель оператора рассматриваются отдельно как UI.

Для нового B24 UI агент один раз подключает и закрепляет точный адрес версии из css.href за gateway или css.publicHref на собственном хостинге. Обновление общего набора не меняет оформление уже созданного приложения. Корень UI обязательно использует font-family: var(--ui-font-family-primary, var(--ui-font-family-system)) без загрузки сетевого шрифта. Для действий выбираются только нужные официальные b24icons из закреплённого выпуска: Vue использует точечные импорты @bitrix24/b24icons-vue/<group>/<Icon>, другие стеки — проверенные локальные SVG. Версия, происхождение, MIT-лицензия и контрольные суммы фиксируются в составе приложения. Полный каталог, runtime CDN, внешние ссылки и скрипты в SVG не нужны. Недоступная версия CSS или небезопасная иконка требуют сообщить о несовместимости, а не подменить ресурс.

Получить ТЗ чертежа

GET /v1/app/blueprints/:slug

Метод HEAD для этого адреса не поддерживается и возвращает 404. Для получения ТЗ используйте GET.

Возвращает сырой markdown технического задания. Ответ — не JSON-конверт: тело ответа — текст ТЗ как есть, с заголовком Content-Type: text/markdown; charset=utf-8.

Параметры

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/app/blueprints/tasks-report?locale=ru" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/app/blueprints/tasks-report?locale=ru" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/app/blueprints/tasks-report?locale=ru', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const specMarkdown = await res.text()

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/app/blueprints/tasks-report?locale=ru', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const specMarkdown = await res.text()

Ответ

При успехе — HTTP 200 с телом text/markdown; charset=utf-8 (не JSON) и заголовком Cache-Control: no-store (ответ намеренно не кэшируется — платформа считает по этим запросам статистику обращений к чертежу).

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

Фрагмент тела для slug=tasks-report:

# Отчёт по задачам

До выбора оформления или вопросов о месте использования и бренде прочитай полный успешный JSON-ответ
`GET /v1/me` с ключом приложения и примени `data.uiDesign` как источник правила оформления нового UI.
Если запрос не удался, блок отсутствует или не поддерживается, сообщи, что правило не прочитано,
и уточни оформление.

## Что делает приложение
Встраиваемое в Bitrix24 приложение-отчёт для руководителя команды. Отвечает на три вопроса одним
экраном: какие задачи уже просрочены, чем занят каждый исполнитель и как за неделю изменилась картина
по статусам. Данные берутся из Задач Bitrix24 в реальном времени, без ручных выгрузок: открыл виджет —
увидел, где затык и кому перекинуть работу. Помогает вести планёрку по цифрам, а не по ощущениям, и
не пропускать задачи, у которых горит дедлайн.

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

404 — неизвестный или скрытый slug:

{
  "success": false,
  "error": { "code": "BLUEPRINT_NOT_FOUND", "message": "Blueprint not found" }
}

Ошибки

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

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

• Ответ — не JSON. Проверяйте тело как текст (res.text()), а не через res.json().
• Параметр locale признаёт только точное значение ru — любое другое значение (включая опечатки вроде RU или отсутствие параметра) молча отдаёт английскую версию ТЗ.
• Список чертежей и их slug не имеет отдельного V1-эндпоинта — раздел «Чертежи приложений» и диалог создания ключа в кабинете уже подставляют правильную ссылку в копируемый промт.
• Тела ТЗ не обещают ролевой доступ внутри приложения: оно ходит в Битрикс24 одним ключом-вебхуком владельца, его правами. При передаче приложения другому сотруднику тот видит то же, что и владелец ключа.

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

• Ключи и авторизация
• Deploy API
• Журнал изменений API