Кастомизация Битрикс24 на платформе Вайбкод: создаём паспорт клиента

Привет! Меня зовут Игорь Росляков, я технический писатель. По приглашению руководителя направления «Маркет и интеграции» Сергея Вострикова готовлю цикл статей на тему ИИ-ассистированной разработки решений для Битрикс24.

Сегодня начинаем новую серию туториалов: будем работать с ИИ-агентами через платформу для вайбкодинга Битрикс24 Вайбкод и создавать полезные приложения почти полностью через интерфейс ИИ. В этой статье я использовал OpenAI Codex.

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

Что будет в этой статье:

• Что делает платформа Битрикс24 Вайбкод

• Что сделаем и зачем это нужно

• Что нужно для повторения нашего проекта

• Составляем план и условия работы

• Реализация

  • 1 — Проектирование структуры проекта

  • 2 — Создание интерфейса и полей на портале

  • 3 — Сбор данных через Entity API и Batch

  • 4 — Деплой на сервер Вайбкод и проверка в портале

  • 5 — Исправление ошибок после реальной проверки

  • Готовая структура проекта

• Что сделаем дальше

Что делает платформа Битрикс24 Вайбкод

Обобщённо — это прослойка между агентом, порталом Битрикс24 и сервером приложения. Платформа выполняет несколько функций. 

Даёт API-ключи. Они нужны, чтобы агент мог обращаться к API: создавать приложение, сервер, смотреть статус и логи.

Даёт OAuth-приложение для Битрикс24. Это отдельный ключ vibe_app_…, через который приложение получает право читать данные портала в рамках установленных прав.

Регистрирует встройки в Битрикс24. Например, наше приложение появится как пункт в левом меню и как вкладка в карточке компании.

Хостит сервер приложения. Агент деплоит код на сервер Битрикс24 Вайбкод, и он становится доступен как приложение через URL.

Даёт доступ к данным Битрикс24 через API-обёртку. Приложение обращается к VibeCode Entity API и Batch, а платформа уже прокидывает запросы к порталу с нужной авторизацией.

Даёт инфраструктурные инструменты: создание сервера, деплой и просмотр логов.

Что сделаем и зачем это нужно

Чтобы собрать сводную информацию о компании, часто приходится вручную обходить вкладки с контактами и сделками, проверять завершённые и запланированные активности и искать дополнительный контекст.

Такой информации может быть много: только записей по звонкам и сделкам могут быть сотни. На поиск этой информации вручную уйдут часы.

Мы сделаем приложение «Паспорт клиента», которое будет делать всё за нас: собирать нужные данные в одном месте и выводить список всех компаний, по которым можно посмотреть информацию:

У нас будет отдельная страница с подробной информацией о компании и дополнительно — дашборд, который будет показывать список компаний-клиентов:

Что нужно для повторения нашего проекта

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

Если мы уже зарегистрированы в системе Битрикс24, переходим в веб-приложение платформы vibecode.bitrix24.tech и нажимаем кнопку «Войти»:

Подключаемся к своему порталу в открывшемся окне и выдаём разрешение на работу с платформой:

Платформа соединяет наш портал и ИИ-инструмент. Для этой связи понадобится API-ключ. Получаем его на странице vibecode.bitrix24.tech/dashboard:

Что можно указать при создании ключа:

Название ключа будет отображаться в списке ключей после создания.

Режим доступа доступен в двух вариантах: Только чтение или Чтение и запись. Режим чтения нужен для безопасных интеграций, которые могут смотреть данные, но не могут ничего менять в портале. Режим Чтение и запись нужен, если приложение должно создавать или изменять данные, регистрировать бота и отправлять сообщения.

Права доступа определяют возможности созданных приложений с новым ключом на портале. Для начала можно выбрать все права, а после создания приложения убрать лишние — ключ можно отредактировать.

Вайбкод определяет доступ к разделам самой платформы, а не портала. 

Срок действия определяет время жизни ключа. 

Лимит запросов определяет, сколько обращений в секунду приложение может отправлять через этот ключ. Ограничение защищает портал от слишком высокой нагрузки, например если из-за ошибки приложение начнёт непрерывно повторять один и тот же запрос.

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

Ключ лучше сохранить в .env-файл, где он будет храниться в переменной:

VIBECODE_API_KEY=vibe_api_… 

Тогда его не нужно пересылать агенту в чате.

После этого остаётся открыть рабочую директорию агента, с которым вы привыкли работать, попросить его взять ключ из .env-файла и дать ссылку на документацию платформы Битрикс24 Вайбкод: https://vibecode.bitrix24.tech/v1/me. 

Составляем план и условия работы

Чтобы повысить надёжность дальнейшей работы, я обрисовал агенту задачу и попросил составить план и сохранить его в .md-файл.

После этого добавил базовые инженерные условия:

• Использовать максимально доступную типизацию: основной код пишем на TypeScript, включаем строгий режим и избегаем any, кроме явно изолированных адаптеров внешнего API.

• Подключать минимум зависимостей: каждая новая runtime-зависимость должна быть нужна для конкретной функции приложения. Если задачу можно безопасно решить стандартными возможностями платформы, зависимость не добавляем.

• Тесты добавлять по максимуму: покрываем адаптер VibeCode API, нормализацию данных, агрегатор паспорта, расчёты метрик, обработку частичных ошибок, UI-состояния и smoke-проверки backend routes.

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

План агент составил подробный, но неравномерный:

1. Составить безопасную базу: создать в папке репозиторий, завести .env, .gitignore и .env.example, проверить VibeCode API, документацию и прямой портал.

2. Подробно изучить нужные разделы документации и составить архитектурную схему реализации приложения, карту по типу «раздел паспорта → endpoint → фильтр → связь → fallback». После этого проверить все доступы к нужным источникам и зафиксировать инженерные ограничения: минимальные зависимости, обязательные тесты и coverage-отчёт.

3. Реализовать приложение и запустить его локально для теста.

4. Провести финальный деплой.

Чтобы следить за исполнением работы, я добавил в план чёткое правило останавливаться после каждого шага и давать подробный отчёт о том, что сделано.

Во время работы у меня периодически возникали проблемы с доступом к платформе из-за сбоев c интернетом, поэтому я попросил агента в конце каждого шага делать мини-отчёт не только по техническому состоянию проекта, но и по доступам. В итоге каждый шаг от агента заканчивался примерно такими статусами:

Проверки:   Секреты: ключ не найден нигде кроме .env.   Тесты: пока не запускались.   Coverage: N/A, потому что scaffold приложения ещё не создан.   VibeCode API: работает.   Документация VibeCode: работает.   Прямой доступ к порталу Битрикс24: всё ещё не работает, DNS/resolve timeout.   Продолжать можно через VibeCode wrapper/API.

Реализация

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

1 — Проектирование структуры проекта

Основную реализацию агент сделал в один заход, и после этого мы вносили правки. 

ИИ учёл требования и сделал приложение на TypeScript со строгой типизацией через tsconfig.json. Runtime-зависимости полностью отсутствовали. Для тестов агент сначала пробовал Vitest, но он оказался тяжеловат и капризен под текущий Node, поэтому заменил на более минимальный стек: встроенный node:test и c8 для coverage.

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

Технически проект делится на несколько слоёв:

• http.ts — маршруты, placement-контекст, ответы сервера.

• passport.ts — бизнес-логика паспорта клиента.

• vibe.ts — клиент VibeCode API.

• ui/pages.ts — HTML-интерфейс.

• Отдельные тесты для конфигурации, HTTP, VibeCode-клиента, паспорта и UI.

Это помогло создать аккуратное разделение: отдельно лежат сбор данных, рендеринг, работа с API.

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

2 — Создание интерфейса и полей на портале

Агент зарегистрировал два места встраивания в интерфейс Битрикс24:

• В панели слева появилась кнопка, по которой должен быть открываться общий дашборд со всеми компаниями.

• В карточке компании открывался паспорт конкретной компании.

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

Ключевая логика на этом этапе простая: что приложение смотрит, откуда его открыли. Если это карточка компании, оно достаёт ID компании из placement-контекста. Если это левое меню, показывает общий дашборд.

В коде src/http.ts это место выглядит так:

// создаём объект url из входящего запроса // это нужно, чтобы одинаково работать и с обычными get-параметрами, и с параметрами placement const url = createRequestUrl(rawUrl, rawBody) // проверяем, что пользователь открыл корень приложения // именно на корень обычно приходит запуск из placement Битрикс24 if (url.pathname === ‘/’) {   // читаем тип placement из параметров запроса   // по нему понимаем, приложение открыли из левого меню или из карточки компании   const placement = getParam(url, ‘placement’)   // если placement равен CRM_COMPANY_DETAIL_TAB, значит приложение открыто как вкладка в карточке компании   if (placement === ‘CRM_COMPANY_DETAIL_TAB’) {     // достаём id текущей компании из placement_options     // это главный контекст: вокруг этой компании дальше строится паспорт     const companyId = extractPlacementCompanyId(url)     // собираем паспорт конкретной компании и отдаём html-страницу встройки     return htmlResponse(200, renderCompanyCardPage({       passport: await loadClientPassport(         companyId ?? ‘не передан’,         createVibeClient(context.auth)       )     }))   }   // если это не вкладка компании, считаем, что открыт общий вход в приложение   // в этом случае показываем общий дашборд со списком компаний   return htmlResponse(200, renderDashboardPage({     data: await loadDashboardData(createVibeClient(context.auth))   })) }

3 — Сбор данных через Entity API и Batch

По ID компании приложение формирует пять batch-команд: отдельно запрашивает саму компанию, связанные контакты, сделки, лиды и активности.

Вместо 5 отдельных запросов мы собираем команды в Batch. Это хорошо показывает экономию, потому что раньше эксперт раньше открывал всё руками, а приложение одним пакетом запрашивает нужные сущности.

Как это записано в коде в src/passport.ts:

// функция формирует первый набор batch-команд для паспорта клиента // на вход приходит id компании, которую пользователь открыл в Битрикс24 function createPrimaryCalls(companyId: string): readonly BatchCall[] {   // пробуем привести id компании к числу   // для некоторых get-запросов entityId удобнее передавать числом   const id = Number(companyId)   // возвращаем массив команд, который потом уйдёт в VibeCode Batch API   return [     // получаем саму карточку компании     // это базовая сущность паспорта: название, телефон, отрасль, выручка, последняя активность     {       id: ‘company’,       entity: ‘companies’,       action: ‘get’,       entityId: Number.isFinite(id) ? id : companyId     },     // получаем контакты, связанные именно с этой компанией     // фильтр companyId не даёт забрать все контакты портала, только релевантные текущей карточке     {       id: ‘contacts’,       entity: ‘contacts’,       action: ‘list’,       params: {         filter: { companyId },         limit: 50       }     },     // получаем сделки компании     // по ним считаются статусы: в процессе, выиграны, проиграны, а также сумма сделок     {       id: ‘deals’,       entity: ‘deals’,       action: ‘list’,       params: {         filter: { companyId },         limit: 50       }     },     // получаем лиды, связанные с компанией     // если лидов нет, приложение покажет пустой источник     {       id: ‘leads’,       entity: ‘leads’,       action: ‘list’,       params: {         filter: { companyId },         limit: 50       }     },     // получаем активности, привязанные напрямую к компании     // ownerTypeId = 4 в нашей модели означает crm-компанию     {       id: ‘companyActivities’,       entity: ‘activities’,       action: ‘list’,       params: {         filter: {           ownerTypeId: COMPANY_ENTITY_TYPE_ID,           ownerId: companyId         },         limit: 50       }     }   ] }

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

src/passport.ts, функция loadDealActivities(client, deals):

// функция догружает активности по найденным сделкам // это второй batch-проход после того, как мы уже получили список сделок компании async function loadDealActivities(   client: VibeClient,   deals: readonly DealSummary[] ): Promise<{   readonly activities: readonly ActivitySummary[]   readonly errors: readonly string[] }> {   // если сделок нет, то и активности по сделкам искать негде   // возвращаем пустой результат без ошибки   if (deals.length === 0) return { activities: [], errors: [] }   // собираем batch-команды для активностей каждой сделки   // ограничиваемся первыми 20 сделками, чтобы не раздувать пакет бесконечно   const calls: BatchCall[] = deals.slice(0, 20).map((deal) => ({     // задаём уникальный id результата, чтобы потом понимать, к какой сделке относится ответ     id: dealActivities_${deal.id},     // работаем с сущностью activities     entity: ‘activities’,     // запрашиваем список активностей     action: ‘list’,     // фильтруем активности по сделке     // ownerTypeId = 2 означает crm-сделку     params: {       filter: {         ownerTypeId: DEAL_ENTITY_TYPE_ID,         ownerId: deal.id       },       limit: 20     }   }))   // отправляем второй batch-запрос через VibeCode API   const batch = await client.batch(calls)   // ответы приходят сгруппированными по id команд   // разворачиваем все списки активностей в один общий массив   const activities = Object.values(batch.results).flatMap((value) =>     asArray(value).map(normalizeActivity)   )   // возвращаем найденные активности и отдельно список ошибок api, если они были   return {     activities,     errors: formatBatchErrors(batch.errors)   } }

4 — Деплой на сервер Вайбкод и проверка в портале

После локальной реализации приложение нужно было сделать рабочим снаружи. Мы подняли сервер на VibeCode, задеплоили Node-приложение, привязали его к OAuth-приложению и зарегистрировали встройки.

Это оказалось самой сложной частью проекта для ИИ-разработки.

Сначала агент решил, что публикация приложения должна идти через обычный мастер Битрикс24 Вайбкод: выбрать сервер, выбрать места показа, нажать кнопку Опубликовать. Из-за этого ИИ раз за разом давал инструкции по работе с UI: где выбрать левое меню, где вкладку компании, какой сервер указать. Это было неверное направление для задачи, потому что смысл проекта был именно в том, что агент должен довести приложение до финальной работы самостоятельно.

Потом выяснилось, что агент запутался между несколькими сущностями в интерфейсе публикации: API-ключом, OAuth-приложением, сервером, каталогом приложений, placement-встройками и Black Hole сервером. Я отправлял в Codex скриншоты, на которых он видел, что приложение как ключ авторизации существует, серверы существуют, но в каталоге приложений приложение не появляется. При публикации через стандартный путь платформа хотела создать или выбрать сервер и пройти настройку через мастер настройки UI:

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

Реальная проблема была в том, что «публикация в каталог» и «регистрация встраиваний в портал» оказались не одним и тем же. Для задачи не обязательно было публиковать приложение в каталог. Нужно было, чтобы оно стало видно в интерфейсе Битрикс24: в левом меню и во вкладке карточки компании. Это решается через placement bind.

Понять это мешали проблемы с доступом: из среды агента мой бизнес-портал был недоступен и возвращал DNS timeout. Поэтому ИИ не мог открыть портал и проверить, что происходит после каждого действия.

В конце концов агент нашёл решение и сделал регистрацию через API Битрикс24 Вайбкод.

Фактически решение было таким:

1. Создать и использовать OAuth-приложение Вайбкод. То есть у нас появилось приложение «Паспорт клиента» с app key вида vibe_app_….

2. Задеплоить сервер приложения. Агент собрал проект, загрузил его на VibeCode Black Hole server и настроил старт:
   npm ci —omit=dev
   npm run start

3. Указать приложению VIBE_APP_KEY. На сервере приложение получило ключ OAuth-приложения, чтобы запросы к Entity API шли от имени установленного приложения, а не от личного API-ключа.

4. Зарегистрировать placements напрямую. Это был главный инсайт для ИИ: вместо прохода публикации через UI агент использовал API-привязку placements.

Нужны были два placement:

LEFT_MENU CRM_COMPANY_DETAIL_TAB

И handler:

https://vibecode.bitrix24.tech/v1/bitrix-handler

Это именно handler Вайбкода, не прямой URL сервера. Это важно, потому что handler прокидывает gateway-авторизацию и открывает приложение корректно внутри портала.

После этого приложение появилось в левом меню как Паспорт клиента и во вкладке карточки компании:

Во время деплоя агент оперативно реагирует на происходящее и держит в курсе процесса, это приятно:

На всякий случай скажу, что посмотреть и настроить свои серверы можно в меню платформы:

5 — Исправление ошибок после реальной проверки

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

Для сохранения авторизации агент начал сохранять авторизацию в подписанную HttpOnly cookie. Для этого понадобились 2 правки в src/http.ts. Сначала — место, где используется авторизация:

// при обработке запроса сначала пытаемся взять свежую авторизацию из заголовка gateway // если заголовка уже нет, пробуем восстановить авторизацию из подписанной cookie authorization:   getHeader(request, ‘x-vibe-authorization’) ??   readSignedAuthCookie(request, config.vibeAppKey)

Потом — место, где создаётся cookie:

// функция создаёт cookie только если есть и авторизация, и ключ приложения // без этих данных сохранять нечего export function createSignedAuthCookie(   authorization: string | null,   appKey: string | null ): string | null {   // если авторизации нет, возвращаем null   // это защищает от установки пустой или бессмысленной cookie   if (!authorization || !appKey) return null   // кодируем значение авторизации в base64url   // так его безопаснее положить в cookie как строку   const value = Buffer.from(authorization, ‘utf8’).toString(‘base64url’)   // подписываем значение через hmac   // подпись нужна, чтобы пользователь не мог подменить cookie вручную   const signature = signCookieValue(value, appKey)   // возвращаем защищённую cookie   // httponly не даёт читать её из javascript   // secure требует https   // samesite=none нужен, потому что приложение работает внутри iframe/placement   return ${AUTH_COOKIE_NAME}=${value}.${signature}; Path=/; Max-Age=3600; HttpOnly; Secure; SameSite=None }

Другие правки были проще — видимая область при открытии во встройке компании была слишком маленькой, а подписи к проигранным сделкам и сделкам в процессе выглядели как просвечивающая техническая часть:

Некоторые недочёты стали видны только после тестирования на реальных сценариях — например, сумма сделок считалась некорректно:

const totalDealAmount = deals.reduce((sum, deal) => sum + deal.amount, 0) const currency = deals.find((deal) => deal.currency)?.currency ?? null

Получался такой алгоритм: 

1. Взять все сделки компании.

2. Сложить amount каждой сделки в одно число.

3. Найти первую сделку, у которой есть валюта.

4. Показать всю сумму в этой первой валюте.

Готовая структура проекта

Итоговый состав приложения выглядит так:

VKVVPart1Passport/ ├─ src/ │  ├─ server.ts │  ├─ http.ts │  ├─ config.ts │  ├─ vibe.ts │  ├─ passport.ts │  ├─ ui/ │  │  └─ pages.ts │  ├─ config.test.ts │  ├─ http.test.ts │  ├─ vibe.test.ts │  ├─ passport.test.ts │  └─ ui/ │     └─ pages.test.ts │ ├─ docs/ │  ├─ DEPLOYMENT_STATUS.md │  ├─ ENGINEERING_STANDARDS.md │  ├─ INVENTORY.md │  └─ TEST_DATA_SCENARIO.md │ ├─ dist/ ├─ coverage/ ├─ node_modules/ ├─ package.json ├─ package-lock.json ├─ tsconfig.json ├─ PLAN.md ├─ .env ├─ .env.example └─ .gitignore

Основные составляющие проекта:

• src/server.ts — точка входа приложения, которая запускает HTTP-сервер на нужном порту.

• src/http.ts — HTTP-слой маршрутизации, который отвечает на несколько вопросов: какой URL открыл пользователь, открыл ли он общий дашборд или карточку компании, какой HTML или JSON вернуть.

• src/passport.ts — главный бизнес-слой, где живёт логика приложения. Этот скрипт понимает, какие сущности нужны, как собрать Batch-запрос, как считать метрики и нормализовывать ответы. При добавлении новых функций основная работа будет здесь.

• src/vibe.ts — клиент VibeCode API. Он знает, куда отправлять Batch, какие заголовки авторизации нужны, как распарсить ответ. Весь контакт с внешним API изолирован в одном месте. Благодаря этому, если поменяется формат ответа или endpoint, не придётся переписывать весь проект. 

• src/ui/pages.ts — серверный HTML-рендеринг. Здесь хранятся общий дашборд, карточка компании, таблицы, метрики, стили. Агент сознательно не стал использовать React/Vue, потому что на этапе первой версии это было бы лишней зависимостью. Нам нужен был быстрый, типизированный и минимальный проект, который можно легко задеплоить на VibeCode-сервер.

• src/*.test.ts — тесты, которые проверяют конфиг, HTTP-роутинг, Вайбкод-клиент, сбор паспорта и HTML-рендеринг.

• docs/ — рабочая документация проекта. Здесь агент сохранил сценарий тестовых данных, статус деплоя, инженерные правила. По этим деталям я частично восстанавливал историю, когда писал статью.

Общий процесс выглядит так:

Что сделаем дальше

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

Если у вас есть вопросы по работе с платформой или предложения по созданию интересных кастомизаций — напишите в комментариях, а мы постараемся об этом написать.

Источник: habr.com