База знаний 2.0 через API в Битрикс24 VibeCode: бот поддержки по вашим регламентам

Что умеет API Базы знаний

Что стало возможным:

• Создавать базы знаний и документы в них программно.
• Наполнять документы контентом из внешних источников.
• Искать по содержимому через полнотекстовый запрос.
• Выгружать документы для резервного копирования или синхронизации.

Всё это делается через единый scope note платформы VibeCode. Документация доступна по адресу https://vibecode.bitrix24.tech/docs/note - актуальные квоты и точный формат запросов сверяйте там, так как платформа находится в активной бете и параметры меняются.

Важно. Все числовые лимиты (размеры квот, допустимые объёмы документов) в этой статье не приводятся намеренно: платформа в активной бете, цифры калибруются. Сверяйтесь с https://vibecode.bitrix24.tech/docs на момент внедрения.

---

Ключевые элементы API: scope, эндпоинт, авторизация

Scope note

Scope note - разрешение ключа VibeCode, которое открывает доступ к объектам Базы знаний портала. Без него запросы к /v1/note/* вернут ошибку авторизации.

При создании ключа в настройках VibeCode необходимо явно включить note в список разрешённых scope. Проверить текущие права ключа можно запросом:

GET /v1/me
X-Api-Key: <ваш_ключ>

Ответ содержит перечень доступных scope и API.

Поиск документов

Основной эндпоинт для работы с содержимым:

GET /v1/note/documents/search
X-Api-Key: <ваш_ключ>

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

Авторизация

Стандартная авторизация VibeCode - заголовок X-Api-Key: <ключ> (альтернатива: Authorization: Bearer <ключ>). Те же правила, что и для остальных Vibe API эндпоинтов. Подробнее о модели ключей - в документации по адресу https://vibecode.bitrix24.tech/docs/keys-auth.

---

Четыре рабочих сценария

Основные потоки данных для четырёх сценариев использования API Базы знаний. Внешние системы и боты взаимодействуют с Vibe API, который через scope note читает и записывает документы в Базу знаний Битрикс24; параллельно эмбеддинги позволяют организовать семантический поиск.

flowchart LR
    USER[Пользователь / чат] -->|вопрос| BOT[Бот поддержки]
    BOT -->|GET /v1/note/documents/search| VIBE[Vibe API]
    VIBE -->|scope note| KB[База знаний Б24]
    ONBOARD[Приложение онбординга] -->|POST создать документ| VIBE
    WIKI[Внешняя вики] -->|синхронизация| VIBE
    VIBE -->|выгрузка Markdown| BACKUP[Бэкап / архив]
    VIBE -->|POST /v1/embeddings| EMB[bitrix/embeddings]
    EMB -->|семантический поиск| BOT

№	Сценарий	Что делает приложение	Направление операции
1	Бот поддержки по регламентам	Принимает вопрос → ищет в базе знаний → отвечает цитатой	Чтение (search)
2	Приложение адаптации новых сотрудников	При найме сотрудника само наполняет его отдел нужными документами	Запись (create/update)
3	Синхронизация с внешней вики	Периодически сверяет содержимое внешнего источника с базой знаний Б24	Чтение + запись
4	Резервное копирование в Markdown	Экспортирует все документы базы знаний в файлы для архива	Чтение + выгрузка

---

Сценарий 1: бот поддержки, который цитирует регламенты

Это наиболее востребованный сценарий для команд технической поддержки и хелпдеска. Логика работы:

1. Сотрудник или клиент задаёт вопрос боту (через чат Битрикс24, открытую линию или мессенджер).
2. Бот передаёт текст вопроса в GET /v1/note/documents/search.
3. API возвращает релевантные фрагменты из базы знаний.
4. Бот передаёт найденные фрагменты в языковую модель (например, bitrix/bitrixgpt-5.5) вместе с вопросом и получает сформулированный ответ.
5. Ответ отправляется пользователю со ссылкой на исходный документ.

Такая архитектура относится к паттерну RAG (retrieval-augmented generation): модель не выдумывает ответ, а опирается на найденные куски реальных документов. Для повышения точности поиска можно дополнительно использовать векторные эмбеддинги - модель bitrix/embeddings через POST /v1/embeddings (scope vibe:ai, бесплатная, OpenAI-совместимая).

Пример минимального запроса поиска:

GET /v1/note/documents/search?query=порядок+возврата+товара
X-Api-Key: <ваш_ключ>

Полный список параметров (фильтры по базе, типу документа, дате) - в документации https://vibecode.bitrix24.tech/docs/note.

---

Сценарий 2: приложение адаптации, которое само наполняет базу

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

Приложение на VibeCode может:

• При срабатывании события (новый пользователь на портале, заполнение CRM-записи с ролью и отделом) запрашивать шаблонные документы.
• Создавать персональный раздел в базе знаний или копировать нужные статьи.
• Формировать чек-лист задач по onboarding-программе прямо из структуры документов.

Такое приложение хорошо сочетается с ботом Битрикс24 - бот приветствует нового сотрудника и сразу отвечает на первые вопросы, опираясь на автоматически созданный раздел базы.

---

Сценарий 3: синхронизация с внешней вики

Если в компании уже есть внешняя база знаний (Confluence, Notion, собственная система), а команда работает в Битрикс24, API позволяет организовать одностороннюю или двустороннюю синхронизацию:

• Одностороннее зеркало: внешняя система является мастером, скрипт периодически читает обновлённые страницы и обновляет соответствующие документы в Б24.
• Двустороннее: изменения в обоих источниках сверяются по дате последнего изменения и сливаются по заданным правилам.

Эту логику удобно реализовать как фоновый сервис на сервере VibeCode (в Галактике - подробнее о деплое), запускаемый по расписанию.

---

Сценарий 4: резервное копирование базы знаний в Markdown

Экспорт документов через API даёт возможность хранить актуальную версию базы знаний вне портала: в git-репозитории, на S3 или локальном хранилище.

Скрипт обхода:

1. Получить список всех документов через GET /v1/note/documents/search (с пагинацией).
2. Для каждого документа запросить содержимое и сохранить в .md-файл.
3. Зафиксировать коммит в git с датой выгрузки.

В результате история изменений регламентов хранится в системе контроля версий - это удобно для аудита и восстановления после ошибочного удаления.

---

Комбинированный сценарий: RAG-ассистент с эмбеддингами

Полнотекстовый поиск хорошо работает для точных фраз, но плохо справляется с семантически близкими, но лексически разными вопросами. Решение - векторный поиск через bitrix/embeddings.

Архитектура RAG-ассистента:

1. При загрузке документа в базу знаний - вычислить его эмбеддинг через POST /v1/embeddings и сохранить вектор в хранилище приложения (VibeCode Storage /v1/storage/*).
2. При вопросе пользователя - вычислить эмбеддинг вопроса.
3. Найти ближайшие по косинусному расстоянию документы.
4. Передать найденные фрагменты в языковую модель как контекст.

Модель bitrix/embeddings бесплатная, OpenAI-совместимая, требует scope vibe:ai. Документация: https://vibecode.bitrix24.tech/docs/ai/embeddings.

---

База знаний Битрикс24: тарифные ограничения платформы

Работа через API не снимает ограничений самого портала Битрикс24 на количество баз знаний (на момент публикации):

Тариф	Базы знаний компании	Настройка прав доступа
Бесплатный	1	Нет
Базовый	3	Нет
Стандартный	5	Да
Профессиональный	Без ограничений	Да
Энтерпрайз	Без ограничений	Да

Базы знаний групп и проектов доступны начиная с тарифа Стандартный. Перед проектированием архитектуры приложения уточните тариф портала клиента - это влияет на количество доступных баз и возможность разграничения прав доступа.

---

Чек-лист запуска бота поддержки по регламентам

Следующий порядок действий подходит для минимально жизнеспособного прототипа за одну сессию вайбкодинга:

• Убедиться, что на портале есть наполненная База знаний с актуальными регламентами
• Создать ключ VibeCode со scope note (и vibe:ai - если нужен RAG)
• Проверить ключ: GET /v1/me - убедиться, что note в списке scope
• Написать (или сгенерировать) обработчик: принять вопрос → GET /v1/note/documents/search → вернуть фрагменты
• Подключить языковую модель (bitrix/bitrixgpt-5.5 или bitrix/bitrixgpt-5.5-agent) для формулировки ответа на основе найденных фрагментов
• Обернуть в бота Битрикс24 или подключить к открытой линии / Telegram-боту
• Задеплоить приложение в Галактику (нулевая цена за размещение)
• Добавить в системный промпт инструкцию: «при неожиданной ошибке - отправь POST /v1/feedback и сообщи номер тикета»
• Протестировать на 10-15 типовых вопросах, сравнить ответы с исходными документами
• Настроить белый список пользователей, которым доступен бот (whitelist в настройках VibeCode)

---

Практические нюансы и типичные ошибки

Пустой результат поиска. Если GET /v1/note/documents/search возвращает пустой массив при наличии документов - проверьте: (1) scope note активен для ключа; (2) документы опубликованы, а не в черновиках; (3) у пользователя/приложения есть права на чтение этой базы знаний (на тарифах Стандартный и выше права настраиваются).

Качество поиска. Полнотекстовый поиск чувствителен к морфологии. Если ответы нерелевантны - рассмотрите комбинацию с векторными эмбеддингами (см. выше).

Объём документов. При выгрузке большого числа документов используйте пагинацию и batch-подход, а не наивный цикл по всем записям - это рекомендованная практика для Vibe API в целом.

Актуальность данных. Бот отвечает по тому, что есть в базе знаний на момент запроса. Если регламенты обновляются редко - это приемлемо. Если часто - настройте уведомление боту или триггер на обновление эмбеддингов при изменении документов.

Командная разработка. При работе нескольких разработчиков над одним приложением - используйте git + worktree, иначе деплои будут перетирать друг друга.

---

Связь с другими возможностями VibeCode

API Базы знаний хорошо работает в связке с другими инструментами платформы:

• Vibe API и модели BitrixGPT - роутер моделей для формулировки ответов на основе найденных фрагментов.
• ИИ-агенты Hermes и Cowork/Code - агент может самостоятельно составлять запросы к базе знаний и использовать результаты в многошаговых задачах.
• MCP-сервер VibeCode - позволяет ИИ вызывать Vibe API как инструмент без ручных curl-вызовов; в том числе работать с базой знаний через команды на естественном языке.
• Смарт-процессы - бот поддержки можно связать со смарт-процессом обращений: документировать неотвеченные вопросы и ставить задачи на обновление регламентов.

---

Вывод и с чего начать

API Базы знаний 2.0 - одно из прикладных обновлений VibeCode, которое превращает статичный справочник в активный компонент автоматизации. Бот поддержки по регламентам, автонаполнение при адаптации, синхронизация с внешней вики, резервные копии в git - всё это реализуется в рамках одного scope и нескольких эндпоинтов.

Платформа находится в активной бете, поэтому перед стартом проекта сверяйтесь с актуальной документацией: https://vibecode.bitrix24.tech/docs/note.

Команда АС Проект - Платиновый партнёр Битрикс24 - помогает проектировать и запускать подобные решения: от выбора архитектуры до деплоя и поддержки.