При интеграции 1С с Битрикс24 через REST API разработчики часто сталкиваются с трудностями при формировании прямых HTTP-запросов. Основная проблема заключается в специфическом синтаксисе фильтров, который отличается от стандартных OData или простых GET-параметров. В этой статье мы подробно разберем, как правильно передавать условия фильтрации, работать с датами, массивами и реквизитами сущностей.
Для получения списка сущностей (например, сделок) используется метод crm.deal.list. Если мы работаем из 1С, нам необходимо сформировать строку параметров запроса. Рассмотрим типичную ошибку: попытку передать операторы сравнения напрямую в строке. Запрос вида "DATE_MODIFY>=2019-01-28" не будет распознан корректно. Битрикс требует передачи оператора внутри ключа массива filter.
Проанализируем правильный синтаксис для фильтрации по дате. Операторы сравнения (>, <, >=, <=, %) ставятся непосредственно перед именем поля внутри квадратных скобок.
Пример формирования фильтра для выбора сделок, измененных в определенном интервале времени:
// Пример формирования строки параметров для HTTP-запроса в 1С
Параметры = "filter[>DATE_MODIFY]=2019-01-31T14:00:00&filter[<DATE_MODIFY]=2019-01-31T17:59:59";
// Полный URL будет выглядеть так:
// https://ваш_портал.bitrix24.ru/rest/1/код_вебхука/crm.deal.list?auth=токен&" + Параметры
Разберем подробнее формат даты. Битрикс24 крайне чувствителен к формату времени. Для корректной работы рекомендуется использовать стандарт ISO 8601. Разделителем между датой и временем должна выступать латинская буква T. Если передавать дату без времени, фильтрация может сработать, но при необходимости точной выборки (например, за последние 2 часа) использование T обязательно.
Посмотрим на частые ошибки:
T. В URL-запросе пробел должен быть заменен на %20, но API Битрикса стабильнее воспринимает именно T.28.01.2019 всегда используйте 2019-01-28.URLEncode для двоеточий в значении времени, хотя современные объекты 1С HTTPЗапрос при правильной сборке параметров делают это автоматически.Выясним, как поступить, если нам нужно получить не одну конкретную сделку, а список сделок с определенными ID. Передача простого списка через запятую не сработает. В REST API Битрикс24 массивы передаются путем явного указания индексов в именах параметров.
Рассмотрим пример запроса для получения сделок с ID 1493 и 1447:
// Правильный формат передачи массива ID в фильтре
Параметры = "filter[ID][0]=1493&filter[ID][1]=1447";
Этот же принцип применим к любым другим полям, поддерживающим множественные значения или фильтрацию по набору условий (например, стадии сделок или ответственные сотрудники).
Часто в 1С требуется передать или получить данные из полей, которые были созданы пользователем вручную (имеют префикс UF_CRM_). Для работы с ними полезно знать два момента:
crm.deal.userfield.list.crm.deal.userfield.get, передав ему ID поля.Помните, что пользовательские поля часто не возвращаются методом list "по умолчанию". Чтобы они появились в ответе, их нужно явно указать в массиве select:
// Пример запроса с выбором конкретных полей
Запрос = "select[0]=ID&select[1]=TITLE&select[2]=UF_CRM_15488528";
Разберем ситуацию, когда данных из карточки компании недостаточно и требуются официальные реквизиты (ИНН, КПП, банковские счета). В архитектуре Битрикс24 эти данные хранятся отдельно.
Для их получения пройдем по шагам:
crm.requisite.list. В фильтре указываем ENTITY_ID (ID вашей компании или контакта) и ENTITY_TYPE_ID (для компаний это 4, для контактов — 3).ID записи реквизита.crm.requisite.bankdetail.list, где в фильтре ENTITY_ID указываем ID реквизита, полученный на предыдущем шаге.Проанализируем производительность. По умолчанию crm.deal.list возвращает только 50 записей. Если сделок больше, в ответе придет параметр next. Чтобы получить следующую порцию данных из 1С, нужно добавить в запрос параметр &start=50, затем &start=100 и так далее, пока общее количество (параметр total) не будет исчерпано.
Если вам нужно минимизировать количество запросов к серверу (актуально для облачных версий с лимитами), рекомендуется использовать метод batch. Он позволяет объединить до 50 различных команд API в один HTTP-запрос. Это значительно ускоряет синхронизацию данных между 1С и Битрикс24.
Для интеграции с 1С наиболее стабильным способом является использование входящих вебхуков. В отличие от OAuth 2.0, вебхук предоставляет постоянный URL с ключом доступа, который не требует регулярного обновления (refresh token). Это упрощает код в 1С, так как нам не нужно хранить дату истечения токена и писать механизмы его пролонгации.
Структура вызова через вебхук:
https://[домен_портала]/rest/[ID_пользователя]/[ключ_вебхука]/[метод]
Используя описанные подходы к фильтрации и форматированию данных, вы сможете построить надежный механизм обмена данными между вашей конфигурацией 1С и CRM-системой Битрикс24.