Произвольный REST-запрос к Битрикс24

Зачем нужен произвольный REST-запрос

Большинство роботов в Битрикс24 решают одну конкретную задачу: находят компанию, меняют поле, создают дело или получают данные письма. Это удобно, пока нужное действие уже есть в каталоге. Но в реальном проекте регулярно появляется запрос, для которого готового робота нет. Например, нужно выбрать элементы смарт-процесса по нескольким условиям, собрать ID сделок для следующего шага или получить только несколько полей из большого ответа.

«Произвольный REST-запрос» закрывает именно этот промежуток между стандартной автоматизацией и отдельной разработкой. Интегратор задаёт операцию Битрикс24, фильтр и набор полей, а робот передаёт полученные данные следующим шагам бизнес-процесса. Не нужно создавать отдельное приложение ради одной выборки или переносить данные вручную.

Это не робот «на все случаи жизни». Лучше всего он подходит для чтения и отбора данных через операции, которые принимают фильтр и список возвращаемых полей. Сложные изменения карточек, многоэтапные обмены с внешними сервисами и операции с нестандартным набором параметров надёжнее делать отдельной интеграцией.

Для кого эта возможность

В первую очередь робот рассчитан на интеграторов Битрикс24, администраторов портала и специалистов по автоматизации. Пользователь должен понимать, где посмотреть описание нужной операции, как устроен JSON и какие коды имеют поля CRM. Обычному менеджеру продаж эти знания не нужны: он работает уже с настроенным процессом и получает готовый результат.

Внутренней IT-службе робот помогает быстро проверить идею. До полноценной разработки можно собрать рабочий сценарий, запустить его на тестовой выборке и понять, достаточно ли стандартных данных Битрикс24. Если задача повторяется, обрастает условиями и требует контроля каждой записи, прототип уже можно переносить в отдельное приложение.

Руководителю отдела робот полезен не напрямую, а через готовую автоматизацию. Например, каждое утро процесс выбирает сделки без следующего дела и ставит задачи ответственным. Руководитель получает контроль, а технический специалист один раз настраивает запрос и правила обработки результата.

Какие проблемы он закрывает

Первая типичная проблема — в конструкторе нет готового действия для нужной выборки. Данные в Битрикс24 есть, права на них есть, но стандартный робот не умеет получить их в нужном разрезе. Произвольный запрос позволяет обратиться к доступной операции и вернуть результат в бизнес-процесс.

Вторая проблема — ответ содержит слишком много лишнего. Если процессу нужны только ID, название и ответственное лицо, нет смысла передавать дальше всю карточку. Поле «Выборка полей» ограничивает состав ответа, а JSONPath извлекает из него конкретные значения. Следующие роботы работают с компактным списком вместо большого JSON.

Третья проблема — ручная подготовка списков. Сотрудник выгружает CRM в Excel, ставит фильтры, копирует идентификаторы и затем запускает действия по каждой карточке. Тот же отбор можно выполнять внутри бизнес-процесса по расписанию. В результате список всегда строится по текущим данным, а не по вчерашней выгрузке.

Четвёртая проблема — зависимость от разработчика при каждой небольшой правке. В готовом запросе интегратор может поменять фильтр, набор полей или путь к результату без выпуска новой версии приложения. Для разовых аналитических и служебных сценариев это заметно сокращает время настройки.

Практические сценарии

Контроль сделок без активности. Процесс по расписанию выбирает открытые сделки нужной воронки, у которых давно не было изменений. В результат попадают ID, название и ответственный. Следующий шаг создаёт задачи менеджерам или отправляет руководителю список проблемных карточек.

Проверка качества базы. Робот выбирает компании, у которых не заполнены ИНН, телефон или отрасль. Полученные ID передаются в цикл: для каждой компании создаётся дело на уточнение данных. Так отдел постепенно очищает базу без общей выгрузки и ручного распределения строк.

Работа со смарт-процессами. Внутренняя служба ведёт заявки на закупку в смарт-процессе. По окончании недели робот выбирает элементы на согласовании, возвращает сумму, автора и дату создания. Бизнес-процесс собирает сводку и отправляет её финансовому директору.

Маршрутизация по связанным данным. Процесс получает список карточек, соответствующих региону, категории клиента или ответственному подразделению. Из ответа берутся только значения, нужные для условия. После этого процесс выбирает ветку и назначает исполнителя.

Проверка гипотезы перед разработкой. Интегратор хочет понять, можно ли получить нужные данные стандартными средствами Битрикс24. Он настраивает запрос, смотрит полный ответ и извлекает нужный фрагмент. Если данных достаточно, сценарий остаётся в бизнес-процессе. Если требуется сложная обработка, уже понятно, что именно передавать разработчику.

Как настраивается запрос

В поле «Метод REST API» указывают название операции из документации Битрикс24. Робот сможет выполнить только доступную операцию, которую поддерживает текущая версия приложения. Перед настройкой стоит проверить, что операция работает с фильтром и выборкой полей. Если ей нужны обязательные параметры другого типа, универсальная форма для неё не подойдёт.

«Фильтр» задаёт условия отбора в формате JSON. Здесь важны точные коды полей, типы значений и операторы сравнения. Неверное имя поля часто не вызывает понятной подсказки: запрос просто возвращает пустой список. Поэтому первый тест лучше запускать с одним простым условием, а остальные добавлять по очереди.

«Выборка полей» определяет, какие данные попадут в ответ. Чем короче список, тем проще использовать результат в следующих шагах и тем меньше лишних данных проходит через бизнес-процесс. Если поле не указано в выборке, ждать его в результате не нужно.

JSONPath нужен, когда из полного ответа требуется извлечь отдельное значение или массив. Например, процессу может понадобиться только список ID. Сначала полезно выполнить запрос без JSONPath, посмотреть структуру полного ответа и только после этого прописать путь. Такой порядок заметно упрощает отладку.

Переключатель «Получить больше 50 элементов» предназначен для больших списков. Его нужно проверять на конкретной операции и тестовых данных: разные разделы Битрикс24 возвращают списки по-разному. Не следует считать включённый переключатель гарантией полной массовой выгрузки, пока количество элементов не сверено.

Поле «Запускать от имени» определяет права запроса. Если выбранный пользователь не видит часть CRM или не может выполнять нужное действие, робот получит тот же запрет. Для рабочего процесса лучше выбирать отдельного пользователя с достаточными, но не избыточными правами.

Что возвращает робот

После выполнения доступны четыре результата. Признак успешного выполнения подходит для условия и позволяет разделить процесс на две ветки. Описание ошибки помогает вывести понятное уведомление администратору. Полный ответ сохраняет исходные данные Битрикс24, а результат по JSONPath содержит только извлечённые значения.

Полный ответ особенно важен при настройке. Если запрос отработал, но JSONPath указан неверно, извлечённый результат может оказаться пустым. При этом в полном ответе данные останутся, и по его структуре можно исправить путь. Поэтому не стоит удалять отладочную ветку сразу после первого успешного запуска.

Если фильтр или список полей содержат некорректный JSON, робот завершит работу с ошибкой и не вернёт данные. Если не указана операция или она недоступна, в описании ошибки будет причина отказа. Следующий шаг процесса должен проверять признак успеха до обращения к результату.

Как встроить в бизнес-процесс

Безопасная схема состоит из трёх частей. Сначала робот получает данные. Затем условие проверяет успешность запроса и наличие результата. Только после этого цикл, уведомление или другой робот обрабатывает найденные элементы. Ошибочная ветка должна отправлять сообщение администратору с описанием ошибки, иначе проблема останется незаметной.

Для списков удобно отделять получение данных от действий над карточками. Первый робот возвращает ID, цикл проходит по ним, а специализированные роботы выполняют понятные операции. Такой процесс легче проверять и восстанавливать после сбоя, чем один универсальный шаг, который одновременно ищет и меняет данные.

Если результат нужен для отчёта, его можно сохранить в переменную, преобразовать в текст и отправить ответственному сотруднику. Если по результату принимается решение, лучше извлечь одно конкретное поле через JSONPath и сравнивать уже его, а не весь JSON целиком.

Ограничения, о которых нужно знать

Робот обращается к данным Битрикс24, а не к произвольным внешним API. Для обмена с бухгалтерией, интернет-магазином или собственным сервисом нужен webhook либо отдельная интеграция.

Универсальная форма передаёт фильтр и список полей. Операции, которым нужны сложные вложенные параметры, пакет команд, файлы или особый формат данных, могут не выполниться. В таком случае проблема не в синтаксисе JSON, а в том, что для задачи нужен специализированный робот.

Массовое изменение сотен карточек лучше не строить на одном произвольном запросе. Здесь важны повторные попытки, журналирование, ограничение нагрузки и понятное восстановление после частичного сбоя. Эти требования проще контролировать в отдельном приложении.

Типичные ошибки

Пустая операция. Робот сразу завершает работу, потому что не знает, к каким данным обращаться. Проверьте, что название заполнено полностью и без лишней точки в начале или конце.

Некорректный JSON в фильтре или выборке. Частые причины: одинарные кавычки, лишняя запятая, незакрытая скобка или список полей, записанный как обычный текст. Сначала проверьте JSON отдельно, затем вставляйте его в робота.

Операция не найдена или не поддерживается. Название может быть написано с ошибкой либо текущая версия приложения не умеет с ней работать. Выберите операцию, совместимую с фильтром и выборкой, или используйте специализированную интеграцию.

JSONPath не возвращает значения. Сам запрос при этом может быть успешным. Откройте полный ответ, найдите реальное расположение данных и исправьте путь. Не пытайтесь подбирать его вслепую.

Недостаточно прав. На тесте под администратором всё работает, а в рабочем процессе результат пустой или приходит отказ. Проверьте пользователя в поле «Запускать от имени» и его доступ к нужному разделу CRM.

Неполный список. Сравните количество элементов с контрольной выборкой в Битрикс24. Для больших объёмов проверьте настройку получения более 50 элементов и убедитесь, что конкретная операция корректно отдаёт продолжение списка.

Когда робот действительно экономит разработку

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

Если сценарий меняет много данных, работает с внешними системами, требует сложных повторных попыток или должен гарантированно продолжаться после частичного сбоя, экономить на разработке не стоит. В этом случае отдельная интеграция будет надёжнее и понятнее в сопровождении.