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

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

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

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

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

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

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

`GET /v1/app/blueprints/:slug`

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

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `slug` (path) | string | да | Идентификатор чертежа из ссылки в скопированном промте |
| `locale` (query) | `ru` \| `en` | нет | Язык тела ТЗ. Любое значение, кроме точно `ru` (включая отсутствие параметра), отдаёт `en` |

## Примеры

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

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

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

```bash
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 — личный ключ

```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-приложение

```javascript
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`:

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

## Что делает приложение
Встраиваемое в Bitrix24 приложение-отчёт для руководителя команды. Отвечает на три вопроса одним
экраном: какие задачи уже просрочены, чем занят каждый исполнитель и как за неделю изменилась картина
по статусам.

## Экраны и функции
- Верхний ряд KPI: всего активных задач, просрочено, завершено за неделю, средний срок закрытия.
- Таблица «исполнитель × активные × просроченные × завершённые», сортировка по числу просроченных.
```

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

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

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 404 | `BLUEPRINT_NOT_FOUND` | Неизвестный или скрытый `slug` |
| 403 | `BLUEPRINTS_DISABLED` | Раздел «Чертежи приложений» не включён для портала ключа |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | Ключ управления (management-ключ) не привязан к порталу — используйте личный ключ или ключ OAuth-приложения |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

- [Ключи и авторизация](/docs/keys-auth)
- [Deploy API](/docs/infra/deploy)
- [Журнал изменений API](/docs/changelog)