# 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` с параметрами фильтрации.

![Список сделок в интерфейсе Telegram](assets/report/deal-list-ui.png)

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

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

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

![Диаграмма последовательности просмотра списка и карточки сделки](assets/report/deal-list-card-sequence.png)

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

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

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

![Карточка сделки в интерфейсе Telegram](assets/report/deal-card-ui.png)

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

## Последствия

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