ADR-005: получение списка и карточки сделки из Битрикс24

Статус: Принято
Дата: 2026-07-23

Контекст

Приложение не копирует CRM-данные в локальную базу. Сведения о сделках, контактах, компаниях, стадиях и истории запрашиваются через REST API непосредственно в момент действия пользователя. PostgreSQL хранит только данные, необходимые для идентификации пользователя и выполнения авторизованных запросов.

Реализация работает с сущностью сделки и методами crm.deal.*. Команды /leads и /lead используются как пользовательские псевдонимы /deals и /deal.

Решение

Для получения и изменения данных применяются следующие методы REST API Битрикс24.

Метод	Назначение	Ключевые параметры
crm.deal.list	Список и пагинация	filter, select, order, start
crm.deal.get	Карточка и контроль состояния	id
crm.deal.update	Ответственный и стадия	id, fields, REGISTER_HISTORY_EVENT
crm.status.list	Стадии воронки и источники	ENTITY_ID, STATUS_ID
crm.contact.get	ФИО и телефон контакта	id
crm.company.get	Название и телефон компании	id
crm.stagehistory.list	История переходов	entityTypeId=2, OWNER_ID
crm.activity.todo.add	Отложенный звонок	ownerTypeId=2, deadline, responsibleId

Таблица ADR-005/1. Используемые методы REST API Битрикс24

Формирование списка

Названия стадий не зашиты в интерфейсе. Метод crm.status.list получает актуальную конфигурацию воронки, после чего первая стадия трактуется как псевдофильтр new. Карта стадий кэшируется в памяти на 300 секунд отдельно для портала, пользователя и категории. Дополнительно добавляется фильтр «Все», не передающий STAGE_ID в Битрикс24.

Размер страницы Telegram равен пяти сделкам, тогда как Битрикс24 может возвращать другое количество элементов за запрос. DealService собирает REST-страницы по полю next до тех пор, пока не сможет выделить диапазон [page * limit; page * limit + limit). Значение total используется для расчёта общего числа страниц. Список сделок запрашивается методом crm.deal.list с параметрами фильтрации.

Рисунок ADR-005/1. Список сделок в интерфейсе Telegram

Формирование карточки

Получение карточки сделки продолжает сценарий работы со списком.

Рисунок ADR-005/2. Диаграмма последовательности просмотра списка и карточки сделки

Карточка загружается методом crm.deal.get, затем обогащается данными связанных сущностей. Для контакта составляется ФИО и выбирается первый телефон; при отсутствии телефона контакта проверяется компания. Идентификаторы источника и стадии преобразуются в человекочитаемые названия. В итоговое сообщение включаются сумма, валюта, ответственный, дата создания и комментарий.

Все динамические строки перед включением в HTML-ответ Telegram проходят html.escape. Длина карточки ограничена 3900 символами, что оставляет запас до ограничения Telegram и предотвращает ошибку отправки из-за длинного комментария. Кнопка назначения отображается только для новой сделки, если текущий пользователь ещё не является ответственным.

Рисунок ADR-005/3. Карточка сделки в интерфейсе Telegram

Последствия

Битрикс24 остаётся источником актуальных CRM-данных, а локальная база не требует синхронизации сделок и связанных сущностей. В качестве дальнейшего развития предусмотрен переход с устаревающих методов crm.deal.* на универсальные методы crm.item.*.

6.2 KiB Raw Blame History