Интеграция с amoCRM

amoCRM — это система учёта клиентов и сделок. Интеграция с amoCRM позволяет передавать информацию о клиентах, плательщиках и услугах из BILLmanager в базу данных amoCRM.

Логика работы

Для интеграции с amoCRM используются следующие сущности:

• контакт — клиент в BILLmanager. При создании или изменении клиента в BILLmanager данные о клиенте выгружаются в amoCRM в виде контакта;
• компания — плательщик в BILLmanager со статусом юридического лица. При создании или изменении плательщика в BILLmanager данные о плательщике выгружаются в amoCRM в виде компании;
• сделка — услуга в BILLmanager. При открытии или продлении услуги в BILLmanager данные об услуге выгружаются в amoCRM в виде сделки.

При настройке интеграции происходит выгрузка данных из BILLmanager в amoCRM. Все необходимые сопоставления сущностей задаются в файле конфигурации.

Синхронизация данных запускается, когда в BILLmanager срабатывают события:

• Синхронизация контактов:
  • регистрация клиента;
  • создание клиента из под администратора;
  • изменение клиента из под администратора;
• Синхронизация компаний:
  • создание плательщика из под клиента;
  • редактирование плательщика из под клиента/администратора;
  • оплата платежа с выбором плательщика;
• Синхронизация сделок:
  • открытие услуги;
  • продление услуги.

Настройка интеграции

Настройка на стороне amoCRM

1. Авторизуйтесь в личном кабинете amoCRM с правами администратора.
2. Перейдите в меню → Создать интеграцию → Внешняя интеграция → кнопка Создать.
3. Укажите основные настройки интеграции:
   1. Ссылка для перенаправления — укажите публичный URL BILLmanager в формате "https://{URL}/billmgr".
   2. Ссылка для хука об отключении — оставьте поле пустым.
   3. Предоставить доступ — выберите "Доступ к данным аккаунта".
   4. Название интеграции.
4. Нажмите кнопку Сохранить.
5. Перейдите в раздел amoМАРКЕТ→ Установленные → выберите созданную интеграцию с BILLmanager → вкладка Ключи и доступы.
6. Сохраните значения из полей — они будут использованы для настроек в BILLmanager:
   1. Секретный ключ.
   2. ID интеграции.

   3. Код авторизации. 

      Код авторизации действителен в течение 20 минут. Если за это время вы не настроите интеграцию на стороне BILLmanager, то код нужно будет получить повторно.

Настройка на стороне BILLmanager

1. Перейдите в раздел Интеграция → Модули → Интеграция с amoCRM → кнопка Установить.
   Если модуль установлен успешно, то в разделе Интеграция появится пункт amoCRM.
2. После установки будет открыта форма Настройки интеграции с amoCRM. Вы можете перейти к настройкам из раздела Интеграция → amoCRM → кнопка Настройки интеграции.
3. Укажите настройки интеграции:
   1. URL интеграции — адрес личного кабинета amoCRM в формате "https://{my_company}.amocrm.ru".
   2. ID интеграции — сохранённое значение из поля ID интеграции в amoCRM.
   3. Секретный ключ — сохранённое значение из поля Секретный ключ в amoCRM.
   4. Перенаправление — публичный URL BILLmanager в формате "https://{URL}/billmgr". URL должен совпадать со значением поля Ссылка для перенаправления в amoCRM.
   5. Код авторизации (одноразовый код привязки) — сохранённое значение из поля Код авторизации в amoCRM.
4. Нажмите кнопку Ok.

Настройка синхронизации данных

Чтобы настроить синхронизацию данных BILLmanager с amoCRM, перейдите в раздел Интеграция → amoCRM.

Таблица Привязки отображает информацию о соответствии сущностей BILLmanager сущностям из amoCRM.

Доступные настройки:

• Условия синхронизации — условия, которым должны удовлетворять сущности BILLmanager, чтобы передаваться в amoCRM;
• Теги — условия, которые будут влиять на тегирование сущностей на стороне amoCRM. Если условия выполняются, то при синхронизации сущностей на стороне amoCRM будет проставлен тег, связанный с этим условием;
• Кастомные поля — сопоставление кастомных полей на стороне amoCRM с характеристиками сущностей в BILLmanager;
• Воронки — условия, которые будут влиять на распределение сделки по различным воронкам и статусам внутри этих воронок.

Чтобы запустить синхронизацию вручную, выполните:

/usr/local/mgr5/addon/amocrm_bin.py --command sync --entity <сущность> --elid <id>

Дополнительно

Логи 

• /usr/local/mgr5/var/amocrm_task.log — синхронизация сущностей BILLmanager с amoCRM;
• /usr/local/mgr5/var/amocrm_action.log — события в интерфейсе BILLmanager, связанные с интеграцией с amoCRM.

Конфигурационные файлы

• /usr/local/mgr5/etc/amocrm/amocrm.conf — настройки интеграции: данные авторизации, теги, кастомные поля, воронки;
• /usr/local/mgr5/etc/amocrm/presets.default — файл с преднастроенным набором значений и валидаторов, доступных при настройке воронок, тегов, условий синхронизации и кастомных полей;

• /usr/local/mgr5/etc/amocrm/presets.custom — файл с пользовательским набором значений и валидаторов, доступных при настройке воронок, тегов, условий синхронизации и кастомных полей.

  Файл создаётся вручную администратором, если нужно добавить свои наборы значений и валидаторов.
• /usr/local/mgr5/etc/amocrm/access_token — токен для взаимодействия по API с amoCRM;
• /usr/local/mgr5/etc/amocrm/refresh_token — токен для обновления access_token после истечения его срока действия.

Добавление пользовательских значений

Чтобы добавить новые значения:

1. Сформируйте объект: 

   • custom_values — объект для извлечения данных выбранной сущности (entity);

   • checkers — объект-валидатор для проверки утверждения. Если SQL запрос возвращает ответ, утверждение истинно.
     Каждое значение представляет собой объект вида:

     {
           "name": "ИНН плательщика",
           "intname": "vat_profile",
           "entity": "company",
           "type": "sql",
           "value": "SELECT vatnum FROM profile WHERE id = __ELID__ AND IFNULL(vatnum, '') != ''"
         }

     Пояснения

     • name:
       • для объекта custom_values — имя поля, которое существует в BILLmanager
       • для объекта checkers — имя поля, которое будет отображено в BILLmanager в настройках синхронизации amoCRM
     • intname — внутреннее наименование
     • entity — сущность в BILLmanager:
       • lead — услуга (сделка)
       • contact — клиент
       • company — плательщик
     • type — тип запроса, принимает значение sql
     • value — запрос, который передаёт информацию по связанной сущности. Вместо макроса __ELID__ будет подставлен ID соответствующей сущности
2. Добавьте объект в файл /usr/local/mgr5/etc/amocrm/presets.custom.

{
  "custom_values": [
    {
      "name": "ИНН плательщика",
      "intname": "vat_profile",
      "entity": "company",
      "type": "sql",
      "value": "SELECT vatnum FROM profile WHERE id = __ELID__ AND IFNULL(vatnum, '') != ''"
    },
    {
      "name": "КПП плательщика",
      "intname": "kpp_profile",
      "entity": "company",
      "type": "sql",
      "value": "SELECT pp.value FROM profile p JOIN profileparam pp ON pp.profile = p.id WHERE p.id = __ELID__ AND pp.intname='kpp' AND IFNULL(pp.value, '') != '';"
    },
    {
      "name": "Тип плательщика ",
      "intname": "type_profile",
      "entity": "company",
      "type": "sql",
      "value": "SELECT IF(profiletype = 1, 'Физ лицо', 'Юр лицо') FROM profile WHERE profiletype IN (1,2) AND id = __ELID__"
    }
  ],
  "checkers": [
    {
      "name": "Клиент с именем AMO",
      "intname": "cus_amoclient",
      "entity": "contact",
      "type": "sql",
      "value": "SELECT id FROM account WHERE id = __ELID__ AND name LIKE '%AMO%'"
    },
    {
      "name": "Услуга клиента с именем AMO",
      "intname": "cus_amoclient_item",
      "entity": "lead",
      "type": "sql",
      "value": "SELECT i.id FROM item i JOIN account a ON a.id = i.account WHERE i.id = __ELID__ AND a.name LIKE '%AMO%'"
    },
    {
      "name": "Плательщик клиента с именем AMO",
      "intname": "cus_amoclient_profile",
      "entity": "company",
      "type": "sql",
      "value": "SELECT p.id FROM profile p JOIN account a ON a.id = p.account WHERE p.id = __ELID__ AND a.name LIKE '%AMO%'"
    }
  ]
}

Таблицы в БД

• amocrm_account2contact — связи между клиентом в BILLmanager и контактом в amoCRM. Поля:

  • id — автоинкрементируемый ID;
  • billmgr_id — ID на стороне BILLmanager;
  • amocrm_id — ID на стороне amoCRM;

• amocrm_profile2company — связи между Плательщиком в BILLmanager и компанией в amoCRM. Поля:

  • id — автоинкрементируемый ID;
  • billmgr_id — ID на стороне BILLmanager;
  • amocrm_id — ID на стороне amoCRM;

• amocrm_item2lead — связи между услугой в BILLmanager и сделкой в amoCRM. Поля:

  • id — автоинкрементируемый ID;
  • billmgr_id — ID на стороне BILLmanager;
  • amocrm_id — ID на стороне amoCRM.