Базовые параметры запроса к Смарт-процессу
Каждый метод REST API для Смарт-процессов требует entityTypeId — числового ID конкретного процесса. Найти его просто: CRM → «Смарт-процессы» → нужный процесс → в URL будет type_id=NNN.
| Параметр | Описание | Пример |
|---|---|---|
entityTypeId |
ID Смарт-процесса (обязательный) | 162, 186, 140 |
select[] |
Список полей в ответе | id, STAGE_ID, UF_CRM_3_... |
filter[поле] |
Условие фильтрации | filter[ufCrm3_1719392632]=1 |
fields[поле] |
Поле для записи (в crm.item.update) |
fields[ufCrm3_1719392647]=2 |
Пользовательские UF-поля в filter и select пишутся в нижнем регистре: ufCrm3_XXXXXXXXX. В fields при обновлении — так же.
flowchart LR
EXT[Внешняя система / ЛК] -->|crm.item.list| B24[Битрикс24 REST API]
B24 -->|массив id + поля| EXT
EXT -->|crm.item.update| B24
B24 -->|ok / error| EXT
Сниппет 1: выборка новых элементов по флагу создания
Стандартный паттерн для интеграций — служебное числовое поле-флаг. Бизнес-процесс Битрикс24 выставляет его в 1 при наступлении события, внешняя система опрашивает портал и забирает только «новые» записи.
Получить все новые элементы (флаг = 1):
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=140
&filter[ufCrm3_1719392632]=1
&select[]=id
Ответ вернёт массив items с полем id. После обработки каждого элемента нужно сбросить флаг — иначе он снова попадёт в следующую выборку.
Сбросить флаг создания (записать 2):
GET /rest/{user_id}/{token}/crm.item.update.json
?entityTypeId=140
&id={ELEMENT_ID}
&fields[ufCrm3_1719392632]=2
Важно. Значение
2означает «обработано» — в отличие от0(не инициализировано) и1(событие произошло). Трёхзначная семантика позволяет чётко отличать необработанные элементы от изначально пустых.
Сниппет 2: отслеживание смены ответственного
Для отслеживания смены ответственного заводятся два служебных поля: флаг (числовое) и предыдущий ответственный (привязка к пользователю). Бизнес-процесс сравнивает текущее поле «Ответственный» с сохранённым предыдущим — при расхождении выставляет флаг в 1.
Запрос элементов, у которых сменился ответственный:
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=140
&filter[ufCrm3_1719392647]=1
&select[]=id
Сброс флага после обработки:
GET /rest/{user_id}/{token}/crm.item.update.json
?entityTypeId=140
&id={ELEMENT_ID}
&fields[ufCrm3_1719392647]=2
Поле «Предыдущий ответственный» (UF_CRM_3_1719392872, тип — привязка к пользователю) хранит значение до последнего изменения. Его можно запросить отдельным select[] — удобно для аудита или уведомлений.
Сниппет 3: отслеживание смены стадии (статуса)
Логика та же, что и со сменой ответственного: бизнес-процесс сравнивает поле «Стадия» с полем «Предыдущий статус» (строка) и при расхождении выставляет флаг.
Получить элементы со сменой стадии:
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=140
&filter[ufCrm3_1719392665]=1
&select[]=id
Получить текущий STAGE_ID конкретного элемента:
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=140
&filter[id]={ELEMENT_ID}
&select[]=STAGE_ID
Сброс флага смены стадии:
GET /rest/{user_id}/{token}/crm.item.update.json
?entityTypeId=140
&id={ELEMENT_ID}
&fields[ufCrm3_1719392665]=2
STAGE_ID — системное поле, не пользовательское. Его не нужно писать через ufCrm3_, оно доступно напрямую в select[] и filter[].
Сниппет 4: инкрементальная синхронизация по дате обновления
Альтернатива флаговому подходу — фильтрация по системному полю UPDATED_TIME. Внешняя система фиксирует у себя timestamp последнего успешного обмена и при следующем запросе передаёт его как нижнюю границу фильтра.
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=140
&filter[>=UPDATED_TIME]=2024-07-01T10:00:00+03:00
&select[]=id
&select[]=UPDATED_TIME
&select[]=STAGE_ID
| Подход | Когда использовать |
|---|---|
| Флаги (UF-поля) | Нужно различать типы событий: создание, смена ответственного, смена стадии |
UPDATED_TIME |
Достаточно знать «что-то изменилось»; меньше служебных полей |
По нашей практике, флаговый подход надёжнее при высокой частоте изменений: UPDATED_TIME может пропустить несколько обновлений, если они попали в промежуток между опросами. О том, зачем вообще нужны Смарт-процессы и чем они отличаются от сделок, читайте в статье Смарт-процессы Битрикс24: когда они заменяют CRM, а когда нет.
Сниппет 5: поиск элемента по уникальному полю и обновление
Типовой сценарий при двусторонней синхронизации — найти элемент по внешнему идентификатору (email или внешний ID) и обновить его поля.
Шаг 1. Найти элемент по уникальному полю:
GET /rest/{user_id}/{token}/crm.item.list.json
?entityTypeId=162
&select[]=id
&filter[ufCrm5_1686147895444]=user@example.com
Если массив items не пуст — элемент есть, берём его id. Если пуст — создаём новый через crm.item.add.
Шаг 2. Обновить найденный элемент:
GET /rest/{user_id}/{token}/crm.item.update.json
?entityTypeId=162
&id={ELEMENT_ID}
&fields[ufCrm5_1686147895444]=user@example.com
&fields[TITLE]=Новое название
Паттерн «найти-или-создать» (upsert) мы используем, например, при интеграции с внешними личными кабинетами и аналитическими платформами. Похожая логика работает и при интеграции Битрикс24 и 1С — там сначала ищется контрагент по ИНН, и только при отсутствии создаётся новый.
Служебные поля: типовой набор для интеграций
В реальных проектах набор служебных UF-полей для одного Смарт-процесса выглядит примерно так:
| Поле | Тип | Назначение |
|---|---|---|
UF_CRM_X_XXXXXXXXX (Флаг создания) |
Число | 1 = новый элемент, 2 = обработан |
UF_CRM_X_XXXXXXXXX (Флаг смены ответственного) |
Число | 1 = ответственный сменился |
UF_CRM_X_XXXXXXXXX (Флаг смены статуса) |
Число | 1 = стадия сменилась |
UF_CRM_X_XXXXXXXXX (Флаг изменения) |
Число | 1 = любое изменение элемента |
UF_CRM_X_XXXXXXXXX (Предыдущий ответственный) |
Привязка к пользователю | Значение до последней смены |
UF_CRM_X_XXXXXXXXX (Предыдущий статус) |
Строка | Значение стадии до последней смены |
UF_CRM_X_XXXXXXXXX (Флаг загрузки файлов) |
Число | 1 = загружен новый файл через БП |
UF_CRM_X_XXXXXXXXX (Ссылки на файлы) |
Ссылка | Обновляемый список URL загруженных файлов |
Все флаги выставляются автоматически бизнес-процессами на стороне Битрикс24 — внешней системе остаётся только опрашивать и сбрасывать. Если в вашем Смарт-процессе задействован модуль согласования договоров, аналогичным образом можно отслеживать смену стадии согласования и уведомлять внешние системы.
Типовые ошибки и как их избежать
1. Неверный регистр имени поля в filter/select
Пользовательские поля в REST API передаются в camelCase с маленькой буквы: ufCrm3_1719392647, а не UF_CRM_3_1719392647. Системные поля (STAGE_ID, UPDATED_TIME, TITLE) — наоборот, в верхнем.
2. Отсутствие entityTypeId
Без этого параметра crm.item.list вернёт ошибку. entityTypeId уникален для каждого Смарт-процесса и не совпадает между разными порталами.
3. Гонка состояний при параллельных запросах Если несколько экземпляров внешней системы одновременно опрашивают портал и сбрасывают флаги — возможна двойная обработка. Решение: атомарный upsert (найти → проверить флаг → обновить) или очередь на стороне интегратора.
4. Флаг не сбрасывается после обработки
Если не записать значение 2 в флаговое поле, элемент снова попадёт в следующую выборку. Сброс флага — последний шаг, после успешной обработки на стороне внешней системы. Не до.
5. Превышение лимита REST API
Битрикс24 по умолчанию ограничивает количество запросов в секунду. При массовой синхронизации используйте batch-запросы или добавляйте задержки между вызовами.