SkyForces
84 lines
6.2 KiB
Markdown
84 lines
6.2 KiB
Markdown
# 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.*`.
|