Поиск реквизитов

Активити (робот) "Поиск реквизитов" предназначено для использования в роботах и может быть полезно в следующих сценариях:

Поиск реквизитов компании или контакта по ИНН, наименованию, коду или другим полям для дальнейшей обработки;
Проверка наличия реквизита с заданными данными перед созданием нового (избежание дубликатов);
Поиск реквизитов по привязке к сущности (контакт или компания) и типу пресета для выбора нужного реквизита в карточке;
Получение списка ID реквизитов для массового обновления, удаления или получения данных в цикле;
Поиск реквизита компании сделки по ИНН или наименованию для подстановки в документы;
Фильтрация реквизитов по активности, дате создания или пользовательским полям;
Интеграция с 1С: поиск реквизита по внешнему коду или коду для синхронизации;
Поиск реквизитов контакта для выбора основного реквизита или проверки заполненности;
Получение первого или последнего реквизита из списка (по дате создания) для автоматического выбора;
Поиск по нескольким критериям (ИНН + пресет, сущность + название) для точного определения реквизита.

Как работает активити (робот):
- Активити (робот) выполняет поиск реквизитов через метод REST API Битрикс24 crm.requisite.list по заданным критериям;
- Условия поиска формируются из заполненных пользователем полей: каждое непустое поле добавляется в фильтр. Пустые поля не участвуют в поиске;
- Необходимо указать хотя бы один параметр поиска. Если ни один параметр не заполнен, активити (робот) завершится с ошибкой «Вы не указали параметры для поиска»;
- Результаты упорядочиваются по дате создания (DATE_CREATE) по возрастанию. Возвращаются ID найденных реквизитов: массив, строка через запятую, первый и последний ID, а также количество найденных записей;
- Если реквизиты не найдены, значение параметра "Успех выполнения операции" = N и запись об ошибке в журнал.

Описание параметров активити (робота)

Название поля	Описание и примеры использования
Тип пресета	Необязательный параметр. Поиск реквизитов только с указанным пресетом (шаблоном). Список пресетов формируется при установке активити (робота) из настроек портала (CRM — Шаблоны реквизитов). Примеры: - Выберите «Юридическое лицо» или «ИП» для поиска реквизитов определённого типа; - Оставьте пустым, чтобы не ограничивать поиск по пресету.
Тип сущности	Необязательный параметр. Ограничение по типу сущности: 3 — Контакт, 4 — Компания. Примеры: - 4 — искать только реквизиты компаний; - 3 — только реквизиты контактов.
ENTITY_ID (ID сущности)	Необязательный параметр. Поиск реквизитов, привязанных к указанному контакту или компании. Примеры: - {=Document:COMPANY_ID} — реквизиты компании из поля документа (сделки); - {=Variable:CONTACT_ID} — реквизиты контакта из переменной; - {=Document:ID} — реквизиты сущности с ID из документа.
Остальные поля для поиска	Набор полей (название, ИНН, КПП, полное и сокращённое наименование, код, внешний код, активность, даты, пользовательские поля и др.) формируется при установке активити (робота) из crm.requisite.fields. Заполняйте те поля, по которым нужно искать. Поддерживаются условия поиска (точное совпадение, вхождение подстроки и др. в зависимости от реализации). Пустые поля в фильтр не попадают. Примеры: - ИНН — поиск по ИНН (например, {=Variable:INN} или конкретное значение); - NAME — по названию реквизита; - Код, Внешний код — для поиска по интеграции с 1С.
Запускать от имени	Сотрудник, от имени которого выполняется действие. Рекомендуется выбирать сотрудника с правами администратора. От прав зависит доступ к реквизитам в CRM.
Устанавливать текст статуса	Позволяет включать установку статуса бизнес-процесса для отображения в истории, на каком шаге остановился процесс. Удобно при отладке.
Текст статуса	Текстовый статус, отображаемый в истории бизнес-процесса при включённом параметре «Устанавливать текст статуса».
Ожидать ответа	Параметр не управляется пользователем; определяет, нужно ли ожидать ответа от активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Ограничение времени ожидания ответа (в секундах, минутах, часах, днях). Рекомендуется не менее 5 минут и не более 1 часа. При истечении времени бизнес-процесс продолжит выполнение по заданной логике.

Примеры использования активити (робота)

Описание примера	Решение
Найти реквизиты компании сделки	ENTITY_ID (ID сущности) — {=Document:COMPANY_ID}, Тип сущности — Компания (4). Остальные поля при необходимости (пресет, название). В результате получите значения в параметрах Результат поиска (массив для итератора) и "Первый результат поиска" для использования в «Получение данных по сущности: реквизит» или «Удаление реквизита».
Поиск реквизита по ИНН	Заполните поле ИНН — {=Variable:INN} или конкретное значение. При необходимости укажите ENTITY_ID — {=Variable:COMPANY_ID} и Тип сущности — 4. Используйте значения параметра "Первый результат поиска" как ID реквизита в следующих шагах.
Проверить, есть ли реквизит у контакта, перед созданием	ENTITY_ID — {=Document:ID}, Тип сущности — Контакт (3). Остальные поля пустые. Проверьте возвращаемый параметр "Успех выполнения операции": если Y и "Количество найденных элементов" больше 0 — реквизит уже есть; если N — можно создавать новый через «Добавление реквизита».
Получить первый реквизит компании по дате создания	ENTITY_ID — {=Variable:COMPANY_ID}, Тип сущности — 4. Результаты отсортированы по DATE_CREATE по возрастанию. Используйте значения параметра "Первый результат поиска" как ID самого раннего реквизита, "Последний результат поиска" — последнего.
Поиск по пресету и сущности	Тип пресета — «Юридическое лицо», ENTITY_ID — {=Document:COMPANY_ID}, Тип сущности — 4. Активити (робот) вернёт только реквизиты юрлица для указанной компании. Подставьте значение параметра "Первый результат поиска" в «Получение данных по сущности: реквизит» для извлечения полей.
Массовая обработка найденных реквизитов	Задайте критерии поиска (например, ENTITY_ID и ИНН). Передайте параметр "Результат поиска (массив для итератора)" в итератор. В цикле для каждого {=Iterator:Value} выполните «Получение данных по сущности: реквизит», «Изменение реквизита» или «Удаление реквизита».
Поиск реквизита по внешнему коду для синхронизации с 1С	Заполните поле «Внешний код» (или код) значением из 1С — {=Variable:EXTERNAL_CODE}. При необходимости добавьте ENTITY_ID. Используйте значение параметра "Первый результат поиска" как ID реквизита для обновления или получения данных.
Найти активные реквизиты компании	ENTITY_ID — {=Variable:COMPANY_ID}, Тип сущности — 4, поле «Активен» — Y (или 1). В результате будут только активные реквизиты. Параметр "Количество найденных элементов" покажет их количество.
Поиск по наименованию реквизита	NAME (Название) — «Основные реквизиты» или {=Variable:REQUISITE_NAME}. В сочетании с ENTITY_ID поиск сузится до реквизита с таким названием у указанной сущности.
Условие по результату поиска	Выполните поиск с нужными параметрами. В следующем шаге «Завершение по условиям» или условие: если значения параметров "Успех выполнения операции" = Y и "Количество найденных элементов" > 0 — ветка «Реквизит найден» (например, обновление); иначе — ветка «Реквизит не найден» (добавление нового).

Возвращаемые параметры данного активити (робота):

- Успех выполнения операции — результат поиска: Y (найдено хотя бы один реквизит) или N (ничего не найдено или ошибка);
- Количество найденных элементов — количество найденных реквизитов (число);
- Результат поиска (массив для итератора) — массив ID найденных реквизитов (для итератора или постраничной обработки);
- Результат поиска (строка) — строка из ID через запятую (например, «12,34,56»);
- Первый результат поиска — ID первого реквизита в списке (по дате создания);
- Последний результат поиска — ID последнего реквизита в списке;
- Сообщение об ошибке — служебное сообщение (при успехе содержит количество найденных записей) или описание ошибки.

Используйте параметры "Первый результат поиска" или "Последний результат поиска"для передачи ID в активити (роботы) «Получение данных по сущности: реквизит», «Изменение реквизита», «Удаление реквизита».

Массив из параметра "Результат поиска (массив для итератора)" передавайте в итератор для обработки всех найденных реквизитов.

Важно о возвращаемых параметрах: Если реквизиты не найдены или не указаны параметры поиска, параметр "Успех выполнения операции" будет равен N.
Проверяйте значение параметров "Успех выполнения операции" и "Количество найденных элементов"перед использованием "Первый результат поиска" и "Результат поиска (массив для итератора)" в следующих шагах, чтобы не передать пустое или неверное значение.

Ограничения и рекомендации:

Параметры поиска:
Необходимо заполнить хотя бы один параметр (тип пресета, тип сущности, ID сущности или любое другое поле реквизита).
Если все поля пустые, активити (робот) завершится с ошибкой «Вы не указали параметры для поиска» и вернёт "Успех выполнения операции" = N.

Результаты не найдены:
Если по заданным критериям реквизиты не найдены, активити (робот) завершится с ошибкой «Результатов не найдено», "Успех выполнения операции" = N.
Обрабатывайте эту ситуацию в условии (например, ветка «Создать реквизит»).

Порядок результатов:
Найденные реквизиты возвращаются в порядке возрастания даты создания (DATE_CREATE).
Первый в списке — самый старый, последний — самый новый (при одинаковых критериях).

Права доступа:
Сотрудник, указанный в поле «Запускать от имени», должен иметь права на просмотр реквизитов в CRM.
Рекомендуется использовать сотрудника с правами администратора.

Ограничение по количеству:
Метод crm.requisite.list может возвращать ограниченное количество записей за один запрос.
При большом числе реквизитов используйте дополнительные критерии (ENTITY_ID, пресет, ИНН и т.д.) для сужения выборки или обрабатывайте массив значений из параметра "Результат поиска (массив для итератора)" порциями.

Ваша корзина пуста

Поиск реквизитов