Добавляем в бизнес-портал Битрикс24 роботов для автоматизации

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

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

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

В проекте я использую AI-стартер — нашу подготовленную ИИ-базу. Это шаблон проекта с инструкциями-промптами для искусственного интеллекта. 

Для получения актуальных методов и параметров для конкретного метода мы используем Bitrix24 MCP server. Дальше в работе опираемся на ответ от сервера.

Игорь Росляков

Технический писатель

Что будет в сегодняшней статье:

• Подготавливаем работу

• Как будет выглядеть работа с роботами

• Строим план и начинаем работу

• Подготовка бэкенда и каркаса для роботов

• Регистрация в портале

• Первый робот: форматирование номера телефона

• Второй робот: нормализация ФИО

• Третий и четвёртый роботы: получение суммы сделок и количества просроченных задач

• Добавляем очередь и worker

• Почему мы не добавили очередь сразу

• Как всё это работает в общем

• Как проверять работу роботов

• Что будем делать дальше

Ссылка на репозиторий: https://github.com/igorrosliakov-bitrix24/Bitrix24-Article2-Adding-4-Robots

Подготавливаем работу

Сначала нужно сделать клон репозитория и провести базовую настройку. Как это сделать, описано по шагам в первой статье в разделе «Копируем и настраиваем проект»:

Для работы с проектом вам нужно будет выбрать AI-агента. В репозиторий вшиты инструкции для Claude и Cursor, но можно выбрать любой другой. Я использовал Codex. 

При настройке можно выбрать 3 варианта бэкенда. Моя реализация написана на Python и Django.

Как будет выглядеть работа с роботами

Главная задача роботов — вычислять и возвращать нужные значения, чтобы потом разработчики могли дальше использовать их в бизнес-логике. Тут есть широкий простор для творчества, ограниченный только воображением. У вас уже есть визуальный UI Kit, подключенный в проекте по умолчанию, а ещё ничто не мешает использовать значения в собственной кастомной реализации приложения.

Если интересно, как работает возвращение значений, вот страница документации, где всё описано:

Мы для наглядности не просто вернём эти значения, но и сразу применим на платформе с видимым эффектом.

Чтобы робот заработал, его нужно подключить к одной из стадий сделок с клиентом. На портале сделки и роботов можно найти в разделе CRM:

Почти на каждой стадии сделки уже есть несколько роботов по умолчанию. На скрине ниже видно 2 наших — для форматирования телефона и нормализации ФИО:

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

Строим план и начинаем работу

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

• Описать задачу максимально просто и вносить правки в проект по мере тестирования. ИИ должен разобраться в инструкциях и сам задать уточняющие вопросы при необходимости.

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

Ты работаешь внутри репозитория bitrix-tools/b24-ai-starter.
Твоя задача -- собрать приложение для Bitrix24 по шагам, а не целиком сразу.


Цель приложения:
создать несколько пользовательских роботов для Bitrix24 с backend-логикой и возможностью поэтапной ручной проверки после каждого шага.


Функциональность роботов:
1. Робот форматирует номер телефона.
2. Робот нормализует текстовые данные ФИО в заданный формат.
3. Робот получает сделки клиента, берёт значения поля суммы и считает общую сумму по клиенту.
4. Робот получает задачи пользователя, отбирает просроченные и возвращает их количество.


Обязательные правила работы:
1. Сначала изучи инструкции проекта:
   - instructions/knowledge.md
   - инструкции по выбранному backend-стеку
   - инструкции по Bitrix24
   - инструкции по queues / workers
2. Не делай всё сразу.
3. Работай строго по этапам.
4. После завершения КАЖДОГО этапа:
   - остановись;
   - не переходи к следующему шагу;
   - выведи список изменённых файлов;
   - кратко объясни, что именно сделано;
   - напиши, как мне проверить результат вручную;
   - напиши ожидаемый результат проверки;
   - напиши, какие команды запускать;
   - если нужны переменные окружения или настройки Bitrix24, перечисли их отдельно.
5. Ничего не скрывай за фразами вроде "остальное доделаю потом".
6. Не выполняй следующий этап, пока я явно не скажу "дальше".
7. На каждом этапе делай минимально необходимое количество изменений.
8. Сохраняй архитектуру чистой: routes / services / workers / Bitrix client / robot handlers.
9. Все роботы должны быть реализованы как отдельные обработчики с понятными именами.
10. Используй очередь там, где это уместно для демонстрации архитектуры, но не усложняй без необходимости.
11. Если для промежуточной проверки удобнее сначала сделать mock-данные, разрешается временный mock, но это должно быть явно помечено, и потом заменено реальным вызовом API Bitrix24.
12. После каждого этапа обновляй краткую документацию в README или отдельном dev-notes файле, чтобы потом это можно было использовать в статье.


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

Этап 0. Анализ стартера
- определи, какие части проекта уже готовы;
- предложи финальную структуру приложения;
- предложи порядок реализации;
- остановись.

Этап 1. Базовый запуск проекта
- настрой локальный запуск выбранного backend;
- проверь, что приложение поднимается;
- добавь минимальный health endpoint / test endpoint;
- остановись.


Этап 2. Каркас интеграции Bitrix24 для роботов
- подготовь общий слой для регистрации роботов;
- подготовь endpoint для вызова robot handler;
- подготовь функцию возврата результата в Bitrix24;
- если нужно, добавь логирование;
- остановись.


Этап 3. Робот форматирования телефона
- зарегистрируй робота;
- добавь входные параметры;
- реализуй обработчик;
- обеспечь возврат результата;
- остановись.


Этап 4. Робот нормализации ФИО
- зарегистрируй робота;
- добавь настройки формата;
- реализуй обработчик;
- обеспечь возврат результата;
- остановись.


Этап 5. Робот суммы сделок клиента
- зарегистрируй робота;
- реализуй получение сделок клиента через Bitrix24 API;
- просуммируй суммы;
- верни результат;
- остановись.


Этап 6. Робот подсчёта просроченных задач пользователя
- зарегистрируй робота;
- реализуй получение задач пользователя через Bitrix24 API;
- отфильтруй просроченные;
- верни количество;
- остановись.


Этап 7. Очередь и worker
- вынеси обработку роботов во входящую очередь;
- добавь worker;
- покажи поток: robot request -> queue -> worker -> result;
- остановись.


Этап 8. Мини-документация  
- собери краткое техническое описание архитектуры;
- перечисли файлы;
- опиши сценарий проверки каждого робота;
- остановись.


Сейчас выполни только Этап 0.

Подготовка бэкенда и каркаса для роботов

Роботов я добавлял по плану из промпта, поэтому дальше буду описывать работу по заготовленным шагам.

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

На 2-м этапе готовим инфраструктуру для будущей работы:

• Реестр роботов.

• Единый endpoint вызова robot handler.

• Общий dispatcher.

• Единый способ вернуть результат в Bitrix24.

• Основу, на которую можно добавить любое количество роботов.

Для проверки в первом мы поднимаем в фоне базу и бэкенд с настройками из .env:

COMPOSE_PROFILES=python,db-postgres docker compose --env-file .env up --build -d database-postgres api-python

Во втором терминале проверяем, что всё работает правильно.

Сначала проверяем Этап 1 и убеждаемся, что с бэкендом всё хорошо и можно выполнять простые публичные проверки без Bitrix24:

curl -s http://127.0.0.1:8000/api/public/health | jq

curl -s http://127.0.0.1:8000/api/test | jq

После этого проверяем Этап 2.

Общая проверка каркаса:

curl -s http://127.0.0.1:8000/api/robots/catalog | jq

curl -s -X POST http://127.0.0.1:8000/api/robots/debug/execute/system_ping 
  -H 'Content-Type: application/json' 
  -d '{"check":"stage2"}' | jq

Проверка ошибки неизвестного робота:

curl -s -X POST http://127.0.0.1:8000/api/robots/debug/execute/unknown_robot 
  -H 'Content-Type: application/json' 
  -d '{"check":"stage2"}' | jq

Что ещё можно проверить:

• curl -s http://127.0.0.1:8000/api/public/health | jq возвращает status: “healthy”.

• …/api/test → тестовое сообщение.

• …/api/robots/catalog → список с system_ping.

• …/api/robots/debug/execute/system_ping → status: “success”, delivery: “local”.

• …/api/robots/debug/execute/unknown_robot → ошибка про неизвестный handler.

• …/api/health → возвращает ошибку, потому что нужна авторизация, а мы ещё не подключили приложение в портал.

Регистрация в портале

Когда проект настроен и база готова и проверена, нужно подключить приложение к своему порталу. Инструкцию по регистрации можно посмотреть в первой статье в разделе «Регистрируем приложение на портале Битрикс24»:

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

Первый робот: форматирование номера телефона

Этап 3 нашего плана. Здесь мы создаём первого робота.

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

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

На первом шаге было сложнее всего, потому что агент отрабатывал механизм регистрации и перерегистрации роботов в портале и общую схему их работы. Я опишу все проблемы, их причины и решения.

Обратите внимание, что роботы регистрируются на этапе установки приложения. Поэтому после добавления нового робота нужно переустановить приложение в портале кнопкой «Переустановить»:

Дальше разбираю, что не работало сразу.

Робот не регистрировался после установки приложения.

Для корректной установки на install-flow нужно отправлять в /api/install и /api/robots/register один и тот же полный payload установки Bitrix24. Если JWT реально отсутствует, не добавлять Authorization.

Робот уже существовал в Bitrix24, и регистрация падала.

Если нужно скорректировать работу робота, его нужно переустановить — то есть переустановить само приложение. В первом варианте робот просил указать, какой именно телефон ему нужно редактировать:

Я решил сделать его более простым в управлении: теперь при добавлении робота в сделку на определённой стадии он просто форматировал все привязанные к сделке номера телефонов. 

Но при повторной установке bizproc.robot.add возвращал Activity or Robot already installed! Попытка просто делать update тоже оказалась ненадёжной, потому что Bitrix24 отвечал No fields to update.

Что нужно делать: не строить регистрацию на update, а если робот уже существует, сначала удалять его через bizproc.robot.delete, а потом создавать заново через bizproc.robot.add. Это особенно важно, если меняются PROPERTIES.

Старое поле Телефон не исчезало из формы робота. 

Это получалось из-за того, Bitrix24 хранит старую схему зарегистрированного робота. В результате обычный update не очищает удалённые PROPERTIES.

Что нужно сразу делать: при изменении схемы робота использовать сценарий delete -> add. После этого в портале удалить старый экземпляр робота со стадии и добавить заново.

Робот вызывался в портале, но backend отвечал 400.

Что нужно сразу делать: в auth_required.py отдельно поддержать robot payload, и если пришёл robot auth, создавать Bitrix24Account прямо из этого payload, не пытаясь прогонять через install-flow модель.

Робот выполнялся, но ничего не менял номера телефонов в карточках участников.

Первый робот был реализован как formatter входной строки, а не как CRM updater. Сначала даже после доработки он не видел сделку, потому что document_id приходил не массивом, а form-ключами вроде document_id[2]. Из-за этого получалось processed_entities=0.

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

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

"document_id": ["crm", "CCrmDocumentDeal", "DEAL_42"]

Но на самом деле ответ приходил как form-поля, например:

document_id[0]=crm
document_id[1]=CCrmDocumentDeal
document_id[2]=DEAL_42

Поэтому сначала робот не мог собрать нормальный document_id и понять, что он вызван именно на сделке DEAL_42.

Во второй версии робот получал payload от Bitrix24 и пытался извлечь document_id. Но наш код был рассчитан только на такой формат:

payload["document_id"]

А Bitrix24 может прислать ответ так:

payload["document_id[0]"]
payload["document_id[1]"]
payload["document_id[2]"]

Или то же самое, но с DOCUMENT_ID[...]. В итоге робот снова не мог стабильно определить сделку. 

Когда агент понял эту особенность архитектуры, то сделал разбор document_id более устойчивым. Робот научился понимать несколько вариантов ответа. После этого он смог получить ID сделки, найти связанные CRM-сущности, считать их телефоны, нормализовать и сохранить обратно.

Как всё должно работать: robot handler должен читать:

• document_id. 

• DOCUMENT_ID.

• document_id[2].

• DOCUMENT_ID[2].

Если документ — это DEAL_*, надо сделать следующее:

• Вызвать crm.deal.get.

• Взять CONTACT_ID и COMPANY_ID.

• Вызвать crm.contact.get / crm.company.get.

• Прочитать PHONE.

• Отформатировать каждый номер.

• Записать обратно через crm.contact.update / crm.company.update.

Чтобы не повторять тех же ошибок, отдайте агенту такой промпт с объяснением всех ошибок и решений:

Этап 3. Робот форматирования телефона для Bitrix24

Цель:
Сделать не "робот для форматирования вручную введённой строки", а реальный CRM-робот, который запускается на сделке/контакте/компании, сам читает телефоны из CRM и сохраняет их обратно.

Обязательные технические требования:
1. Регистрация роботов
- Должен быть отдельный сервис регистрации роботов.
- Не использовать только bizproc.robot.update.
- Если робот уже существует, делать:
  1) bizproc.robot.delete
  2) bizproc.robot.add
- Это обязательно, иначе Bitrix24 сохраняет старые поля формы робота.

2. Install flow
- После /api/install вызывать /api/robots/register тем же OAuth payload, который пришёл от Bitrix24.
- Не отправлять пустой Authorization header.
- Не рассчитывать, что robots/register сможет отработать только по JWT.

3. Авторизация robot handler
- Endpoint /api/robots/execute/<robot_code> должен уметь принимать robot payload Bitrix24.
- Нужно поддержать оба формата auth:
  - auth = {...}
  - auth[access_token], auth[refresh_token], auth[domain], auth[member_id], ...
- Для robot request нужно создавать временный Bitrix24Account прямо из robot auth payload.
- Не пытаться прогонять robot payload через install-only OAuthPlacementData без адаптации.

4. Разбор document_id
- Нужно поддерживать все варианты:
  - document_id как массив
  - DOCUMENT_ID как массив
  - document_id[2]
  - DOCUMENT_ID[2]
- Иначе робот будет запускаться, но не сможет понять, на какой CRM-документ он вызван.

5. Реальная бизнес-логика робота
- Если документ = DEAL_<id>:
  - вызвать crm.deal.get
  - взять CONTACT_ID и COMPANY_ID
  - обработать телефоны контакта и компании
- Если документ = CONTACT_<id>:
  - обработать телефоны контакта
- Если документ = COMPANY_<id>:
  - обработать телефоны компании

6. Форматирование телефонов
- Удалять все нецифровые символы.
- Если номер из 11 цифр и начинается с 8, заменять первую цифру на 7.
- Если номер из 10 цифр, добавлять default_country_code спереди.
- Если после нормализации длина 11-15 цифр, возвращать +<digits>.
- Если номер невалидный, не портить его.

7. Обновление CRM
- Читать PHONE как множественное поле.
- Для каждого элемента PHONE сохранять:
  - VALUE
  - VALUE_TYPE
  - ID, если пришёл
  - TYPE_ID, если пришёл
- Если хотя бы один номер изменился:
  - вызывать crm.contact.update или crm.company.update
  - передавать весь обновлённый PHONE целиком

8. Настройки робота в Bitrix24
- Не делать обязательное поле "Телефон", если робот сам читает CRM.
- Оставить только служебные настройки, например:
  - default_country_code
- Иначе пользователь будет думать, что туда надо вручную вводить номер, хотя рабочий сценарий должен идти из CRM-контекста.

9. Что возвращать из робота
- processed_entities
- updated_entities
- updated_phone_count
- entity_summary
- log_message с краткой сводкой
Это сильно упрощает отладку через сессии роботов в Bitrix24.

10. Локальная отладка
- Можно оставить debug endpoint для локальной проверки handler'ов без портала.
- Но временные диагностические роботы типа system_ping не должны оставаться в финальной рабочей версии.

Какие файлы должны быть продуманы сразу
auth_required.py -- должен иметь поддержка robot auth.
robot_registration_service.py -- должен иметь схему delete -> add.
robot_registry.py -- здесь не должно быть обязательного поля Телефон для боевого робота.
format_phone_handler.py -- должен включать orchestration-слой.
crm_phone_sync_service.py -- должен включать основную логику чтения/нормализации/обновления телефонов.
install.client.vue -- здесь нужно корректно отправлять payload на регистрацию роботов.
api.ts -- здесь нельзя слать пустой bearer token.

Второй робот: нормализация ФИО

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

Из существующей программы мы использовали несколько уже готовых вещей: общие robot registry, robot dispatcher и robot result service, уже настроенный Bitrix client и решённый разбор document_id. Ещё мы взяли отработанную схему «робот запускается на сделке, backend сам идёт в CRM и обновляет связанные сущности».

Новый робот не должен просить строку ФИО в настройках. Он должен запускаться на сделке и сам находить участников сделки в CRM.

Что нужно менять для карточки контакта:

• LAST_NAME.

• NAME.

• SECOND_NAME.

Для компании нужно менять CONTACT_PERSON.

Нормализацию имени вынесли в отдельную маленькую функцию. Она не знает ничего про Bitrix24, а только приводит слова к виду «С Заглавной Буквы». После этого сделали отдельный CRM-sync сервис. 

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

Такая работа — уже не маленькая функция, а полноценный сценарий работы. Поэтому агент не стал добавлять его в handler, чтобы handler не получился слишком большим. Как распределились функции:

• handler запускает сценарий и собирает результат. 

• Функция нормализации умеет только превратить иВАНОВ в Иванов.

• CRM-sync сервис умеет пройти весь путь по CRM: от сделки до контакта/компании и обратно в update.

То есть CRM-sync сервис — это «исполнитель CRM-части работы».

Когда я подключил нового робота в общую архитектуру, то добавлял его в реестр роботов, dispatcher и отдельный handler. Получилось, что агент добавил нового робота по уже действующему плану:

1. Взял готовую архитектуру роботов.

2. Добавил новую бизнес-логику как отдельный CRM-service.

3. Подключил новый handler.

4. Зарегистрировал новый robot code в registry.

5. Убрал настройки из формы.

6. Оставил общий pipeline запуска и возврата результата без изменений.

Третий и четвёртый роботы: получение суммы сделок и количества просроченных задач

Когда сценарий был отработан, я добавил 2 роботов за один шаг.

• Робот суммы сделок берёт клиента текущей сделки и ищет другие сделки этого клиента. 

• Робот просроченных задач берёт ответственного текущей сделки и ищет его задачи.

Примерная схема их работы выглядит так: робот запускается на сделке → backend сам идёт в CRM/API → возвращает результат. 

Значения возвращаются в виде массива RETURN_VALUES, и их можно использовать дальше. Для демонстрации и проверки оба робота пишут видимый текст в таймлайн текущей сделки. Можно сделать по-другому и добавить в функции роботов отправку всплывающих уведомлений с полученными данными. Но такие сценарии — не наша рекомендация к реальной бизнес-логике, а просто реализованное поведение, которое можно увидеть и исправить в случае ошибок. 

Это выглядит как комментарии, которые появляются в карточке сделки:

В остальном всё работает так же: бизнес-логика находится в отдельных сервисах, handler не хранит всю интеграционную логику внутри себя.

Робот sum_client_deals:

• извлекает DEAL_<id> из document_id;

• вызывает crm.deal.get;

• определяет клиента: сначала COMPANY_ID, а если компании нет, то CONTACT_ID;

• делает crm.deal.list по этому клиенту и суммирует OPPORTUNITY.

Как результат, возвращает количество сделок, общую сумму, валюту, тип клиента и ID клиента. Дополнительно пишет текст результата в таймлайн сделки.

Робот count_overdue_tasks:

• извлекает DEAL_<id> из document_id и вызывает crm.deal.get;

• берёт ASSIGNED_BY_ID и вызывает tasks.task.list;

• фильтрует задачи: дедлайн прошёл, задача не закрыта;

В итоге он возвращает ID ответственного, сколько задач проверили и сколько из них просрочено. Дополнительно пишет текст результата в таймлайн сделки.

В общей архитектуре роботы подключены в robot_registry.py. Их можно найти по меткам code="sum_client_deals" и code="count_overdue_tasks".

У обоих роботов properties = {}, то есть в форме робота нет пользовательских настроек. Ещё для них зарегистрированы return_properties.

Где можно найти точные реализации:

• В robot_dispatcher.py их можно найти по "sum_client_deals": handle_sum_client_deals и "count_overdue_tasks": handle_count_overdue_tasks.

• В robot_handlers/__init__.py можно найти экспорт handle_sum_client_deals и экспорт handle_count_overdue_tasks.

• В services/__init__.py есть экспорты CRMTimelineService, DealSumService и TasksOverdueService.

Добавляем очередь и worker

Идея для этого этапа такая: раньше robot request обрабатывался прямо в HTTP endpoint. Теперь endpoint может быстро принять запрос, положить его в RabbitMQ и сразу ответить Bitrix24. После этого отдельный worker забирает задачу и выполняет того же самого робота.

Что это даёт:

• HTTP endpoint становится лёгким и быстрым.

• Тяжёлую обработку можно вынести из web-процесса.

• Бизнес-логика роботов не дублируется.

Какие сущности за что отвечают:

view / endpoint принимает запрос от Bitrix24.

RobotQueueService кладёт задачу в очередь.

Celery worker достаёт задачу из очереди.

RobotExecutionService — общий pipeline исполнения любого робота.

dispatcher выбирает конкретный handler.

handler выступает как orchestration одного робота.

service хранит реальную бизнес-логику роботов.

RobotResultService отправляет результат обратно в Bitrix24.

Как работала система раньше:

Bitrix24 -> /api/robots/execute/<robot_code> -> handler -> result

Как работает теперь:

Bitrix24 -> /api/robots/execute/<robot_code> -> queue worker -> RobotExecutionService -> handler -> RobotResultService

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

Почему мы не добавили очередь сразу

Очередь не решает базовые интеграционные проблемы Bitrix24. До неё нужно было сначала стабилизировать и проверить:

• Регистрацию роботов.

• Вызов handler из Bitrix24.

• Авторизацию robot request.

• Разбор document_id.

• Бизнес-логику самих роботов.

• Возврат результата в Bitrix24.

Если бы мы начали с очереди раньше, мы бы просто отлаживали те же ошибки, но уже через ещё слой очередь и и worker.

Как всё это работает в общем

Чистый стартер уже умел установиться в портал, принять авторизацию от Bitrix24, сохранить портал и токены, обслуживать backend-запросы. Но там не было архитектуры для роботов: регистрации, описания логики, воркеров, связующего dispatcher-скрипта для нескольких роботов и бизнес-логики.

В итоговый проект мы добавили 5 слоёв:

Слой входа: endpoint для принятия вызовов роботов из Bitrix24, установка и регистрация, дебаг-endpoints для локальной проверки.

Слой маршрутизации роботов: реестр роботов, dispatcher и единый пайплайн исполнения.

Слой обработчиков: тут есть по одному handler на каждого робота. Сам handler почти не делает бизнес-логику, а только координирует вызовы сервисов, поэтому можно сказать, что это небольшой оркестратор.

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

Асинхронный слой для RabbitMQ и Celery worker. Даёт возможность выполнять robot request через очередь, не ломая основной код.

Если смотреть на структуру только новой части проекта, вот какие скрипты мы добавили или изменили:

backends/python/api/
├── celery_app.py                  # Celery app для worker
├── init.py
└── main/
    ├── views.py                   # тонкие HTTP endpoints
    ├── urls.py
    ├── models.py
    ├── robot_handlers/
    │   ├── init.py
    │   ├── format_phone_handler.py
    │   ├── normalize_full_name_handler.py
    │   ├── sum_client_deals_handler.py
    │   └── count_overdue_tasks_handler.py
    ├── services/
    │   ├── init.py
    │   ├── bitrix_client.py
    │   ├── robot_registry.py
    │   ├── robot_dispatcher.py
    │   ├── robot_result_service.py
    │   ├── robot_execution_service.py
    │   ├── robot_queue_service.py
    │   ├── crm_phone_sync_service.py
    │   ├── crm_name_sync_service.py
    │   ├── deal_sum_service.py
    │   ├── tasks_overdue_service.py
    │   ├── crm_timeline_service.py
    │   └── full_name_normalizer.py
    ├── utils/
    │   ├── bitrix_account_factory.py
    │   └── decorators/
    │       └── auth_required.py
    └── workers/
        ├── init.py
        └── tasks.py              # Celery task entrypoint

Какой файл за что отвечает:

views.py принимает HTTP-запросы. Это тонкий входной слой. Самой бизнес-логики тут почти нет.

robot_registry.py описывает всех роботов. Здесь есть код, имя, описание, входные/выходные свойства, handler URL и параметры регистрации в Bitrix24.

robot_dispatcher.py связывает robot_code с конкретным handler.

robot_execution_service.py — единая точка запуска робота. Сюда сходятся sync- и async-пути запуска робота:

1. sync-путь запускает робота сразу, когда backend сам прямо в момент HTTP-запроса выполняет робота.

2. async-путь запускает робота через очередь, когда backend не выполняет робота сам, а кладёт задачу в RabbitMQ, а потом отдельный worker выполняет её позже.

robot_result_service.py отвечает за финальную отправку результата обратно в Bitrix24 через bizproc.event.send.

robot_queue_service.py кладёт задачу в очередь.

robot_handlers/ для каждого робота. Каждый handler только координирует вызовы сервисов и собирает результат. 

services/ включает настоящую полезную логику роботов: телефоны, имена, сделки, задачи, таймлайны, нормализация текста.

bitrix_account_factory.py умеет из robot payload восстановить Bitrix account/token context. Это важно и для HTTP, и для worker.

Что такое robot payload: когда Bitrix24 вызывает нашего робота, он говорит не просто «запусти вот этот код», а ещё и прикладывает служебные данные: с какого портала пришёл вызов, какой access token использовать, что это за пользователь и какие ещё есть auth-данные есть у этого запуска. Всё это лежит внутри входящего запроса робота. Это и есть robot payload.

Но нашему бэкенду недостаточно иметь такой сырой запрос. Ему нужно превратить эти данные в нормальный рабочий объект, куда будут входить домен портала, access token, refresh token, member id. Без этого бэкенд просто не будет знать, в какой портал Битрикс24 обращаться и с каким токеном.

bitrix_account_factory.py делает именно то, что нужно бэкенду: переводит сырые данные в понятный набор информации.

workers/tasks.py — entrypoint для worker: Celery task получает job и запускает общий execution pipeline.

celery_app.py — конфигурация Celery и RabbitMQ.

Если бизнес-логика в скриптах написана специально для определённого робота, в коде это отмечено комментариями с пометками Robot 1, 2, 3 или 4.

Ссылка на репозиторий: https://github.com/igorrosliakov-bitrix24/Bitrix24-Article2-Adding-4-Robots

Как проверять работу роботов

Сначала роботов нужно добавить на нужную стадию. Нажмите «Создать» и найдите нового робота (или роботов, если создали несколько). 

После этого нажмите «Добавить» и перетащите их на нужную стадию сделки, где они будут запускаться:

В этом же разделе включите отладчик:

После этого выберите запуск «Отладки на тестовой сделке»:

Окно отладчика роботов нужно сдвинуть в сторону и выбрать «Сделку в отладке»:

Внутри сделки вставьте на место компании или контакта заранее созданные карточки. Для первых 2 роботов мы создали контакт с неотформатированными ФИО и номером телефона:

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

Что будем делать дальше

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

Если у вас есть тема, про которую вам интересно почитать, напишите её в комментариях, а мы попробуем включить её в новые статьи — или написать отдельную.