Перейти к основному содержимому
Версия: 1.6.0

Интеграции

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

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

Процесс настройки интеграции состоит из четырех этапов:

  1. Создание интеграции.
  2. Создание параметров интеграции.
  3. Создание трансформаций.
  4. Применение данных, полученных через интеграцию
подсказка

Требуемая роль: admin, crm_admin.

Создание интеграции​

Для настройки интеграции вам необходимо создать ее запись в таблице Интеграции CRM (crm_integration) и составить скрипт интеграции. Чтобы сделать это, выполните следующие шаги:

  1. Перейдите в CRM → Параметры → Интеграции.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти.

Поля формы Интеграции CRM

ПолеОбязательноОписание
НаименованиеДаУкажите наименование интеграции.
ТаблицаДаУкажите таблицу, в которой вы будете применять данные из интеграции. Значение данного поля является объединяющим признаком, по которому система проверяет ответы от интеграций через обработчик, когда для одной таблицы настроено более одной интеграции.
ЛогинНетУкажите логин, по которому можно авторизоваться у провайдера API.
Токен доступаНетУкажите уникальный ключ авторизации пользователя, сгенерированный провайдером API.
АктивнаНетУстановите флажок, чтобы интеграция была активна.
URL интеграцииНетУкажите ссылку на API стороннего сервиса, куда система будет посылать запросы.
ПарольНетУкажите пароль, с которым можно авторизоваться у провайдера API.
ПорядокНетУкажите порядок выполнения текущей интеграции по отношению к другим интеграциям. Чем ниже порядок, тем раньше система попытается получить значение параметра интеграции через эту интеграцию относительно других, если для одного параметра созданы трансформации более чем через одну интеграцию. Если ответ интеграции не будет содержать нужную информацию, система перейдет к следующей по порядку.
Скрипт интеграцииДаУкажите серверный скрипт интеграции.
примечание

Поля Логин, Токен доступа, URL интеграции, Пароль не обязательны для заполнения, так как механизм интеграции может отличаться для различных внешних сервисов. Используйте именно те параметры, которые требует ваш провайдер API.

При составлении скрипта интеграции, обратите внимание:

  • Объектом current в данном случае является текущая запись интеграции. Обращайтесь к нему, чтобы получить значения полей записи, если вы не хотите прописывать эту информацию в самом скрипте. Пример: используйте current.getValue('integration_url'), чтобы обратиться к значению поля URL интеграции.
  • В скрипт интеграции передается объект integrationOptions, который содержит данные для запроса к стороннему API. Сам объект integrationOptions формируется и передается при вызове обработчика new CRMIntegrationHandler, который вы можете использовать в других скриптах для получения данных из интеграции: 
    new CRMIntegrationHandler(
        'tableName' – название таблицы, в которой вы будете применять данные из интеграции; это значение является объединяющим признаком, по которому система проверяет ответы от интеграций, когда для одной таблицы настроено более одной интеграции, 
        ['full_name', 'short_name'] – параметры интеграции из таблицы crm_integration_parameter, 
        { request_data: 'request information'} – объект integrationOptions
    );
  • Все ошибки, которые могут возникнуть при выполнении HTTP-запроса к стороннему сервису, необходимо учесть в скрипте интеграции. Вы можете добавить описания ошибок, чтобы записи о них отображались в Основном журнале. Если ошибки не прописаны, и интеграция не вернет ничего или вернет пустой объект, обработчик продолжит свою работу перейдя к следующей интеграции без добавления записей в Основной журнал.
  • Интеграция всегда должна возвращать объект, даже если он пуст.

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

На форме интеграции доступен связанный список Трансформации, который содержит все трансформации, созданные для данной интеграции.

внимание

При удалении записи интеграции, связанные с ней записи трансформаций также будут удалены.

Создание параметра интеграции​

После создания записи интеграции, создайте в таблице Параметры интеграций (crm_integration_parameter) записи параметров, в которые вы будете сохранять данные, полученные через интеграцию. Чтобы сделать это, выполните следующие шаги:

  1. Перейдите в CRM → Параметры → Параметры интеграций.
  2. Нажмите Создать и укажите уникальное Наименование параметра, по которому вы в дальнейшем сможете обращаться к параметру через скрипты.
  3. Нажмите Сохранить или Сохранить и выйти.

Повторите шаги 1-3 для каждого параметра, который вы хотите получать через интеграцию.

Создание трансформации​

После создания параметров, создайте записи в таблице Трансформации (crm_mapping), чтобы указать, какому свойству внешнего API соответствует каждый созданный параметр. Чтобы сделать это, выполните следующие шаги:

  1. Перейдите в CRM → Параметры → Трансформации.
  2. Нажмите Создать и заполните поля.
  3. Нажмите Сохранить или Сохранить и выйти.

Поля формы Трансформации

ПолеОбязательноОписание
Свойство внешнего APIДаУкажите ключ из ответа API интеграции, которому соответствует параметр, для которого вы создаете трансформацию.
Параметр интеграцииДаУкажите параметр, для которого вы создаете трансформацию.
АктивнаНетУстановите флажок, чтобы система использовала эту трансформацию.
Использовать скрипт обработкиНетУстановите флажок, чтобы создать скрипт, через который система будет обрабатывать данные, полученные от внешнего API. Это может быть полезно, если вам необходимо изменить формат, в котором приходят данные от внешней системы, перед их использованием на вашем экземпляре.
Скрипт обработкиНетСоставьте серверный скрипт, с помощью которого система будет обрабатывать данные. Скрипт должен возвращать обработанное значение.
ИнтеграцияДаУкажите интеграцию, для которой вы создаете трансформацию. Обратите внимание, что один и тот же параметр интеграции может трансформироваться более чем через одну интеграцию. В таком случае вам необходимо создать отдельную запись трансформации для каждой интеграции.

Использование интеграций​

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

Скрипт ниже задает логику бизнес-правила, которое автоматически заполняет поле Полное наименование таблицы Компании клиентов при указании ИНН:

Пример скрипта, использующего интеграцию

  (function executeRule(current, previous = null /*not null only when action is update*/) {
    /*global CRMIntegrationHandler: readonly*/
    ss.importIncludeScript('CRMIntegrationHandler');
    const integrationHandler = new CRMIntegrationHandler('crm_customer_company', ['full_name'], { tin: current.getValue('inn') });
    const integrationsData = integrationHandler.getData();

    if (Object.hasOwn(integrationsData, 'full_name')) {
        current.setValue('full_name', integrationsData.full_name);
        return;
    }

    current.setValue('full_name', '');
  })(current, previous);