Интеграция с AMO CRM

Общее описание интеграции

Интеграция реализована с возможностью максимально возможного варианта переноса на другое решение. Для этого в настройках экземпляра Фалькона создана категория настроек amo, в которой созданы переменные:

Вариант интеграции реализован со следующими допущениями: 

• в amoCRM используются следующие списочные сущности:
• Контакты
• Компании
• Товары/курсы
• в amoCRM используются следующие виды воронок для сделок:
• Поставщики (регистрация)
• Создание продукта
• CPC расчет по поставщикам
• Учащиеся
• Прохождение курсов
• все настраиваемые в amoCRM типы полей статичны и данные о них сведены в таблицу соответствия в БД xx_amoFields.
• воронки в amoCRM и их статусы являются статичными  и данные о них сведены в таблицы соответствия в БД xx_amoFunnels, xx_amoFunnelStatuses.

Для работы по API в экземпляре пользователя amoCRM создана интеграция с нашей платформой: Настройки->Интеграции->Создать интеграцию

Для первичной авторизации вводим свои данные и получаем код авторизации, данные заносим в настройки экземпляра Фалькона.

Методы API

Для реализации работы реализованы атомарные методы API в экземпляре Фалькона (разные методы для создания и изменения сущностей и сделок - вынужденное решения, так как используются разные протоколы запросов post и patch):

• авторизация:
• amo_access_token - обмен кода авторизации на access token и refresh token
• amo_refresh_token - получение нового access token по его истечении
• получение данных:
• amo_account -  получение данных аккаунта
• создания/изменения сущностей:
• amo_create_contact (post)
• amo_modify_contact (patch)
• amo_create_company (post)
• amo_modify_company (patch)
• amo_create_product (post)
• amo_modify_product (patch)
• создания/изменения сделок:
• amo_create_deal_supplier (post)
• amo_modify_deal_supplier (patch)
• amo_create_deal_product (post)
• amo_modify_deal_product (patch)
• amo_create_deal_srs (post)
• amo_modify_deal_srs (patch)
• amo_create_deal_student (post)
• amo_modify_deal_student (patch)
• amo_create_deal_course (post)
• amo_modify_deal_course (patch)

Для удобства использования интеграции программистами на платформе реализована возможность вызова через один агрегатный метод цепочки обращений к API amoCRM, для чего  созданы следующие методы:

• сервисные:
• amo_next_action - вызов, при необходимости, авторизации и актуализации токена, с последующим вызовом цепочки обращений к методам API
• amo_xxxxx_next - псевдо-метод для построения цепочек запросов к amoCrm
• агрегатные:
• amo_modify_user - amoCrm - создание/изменение пользователей любой роли 
• amo_modify_course - создание/изменение курса
• amo_modify_usercourse - создание/изменение сделок прохождения курса

Все методы, за исключением amo_next_action, по завершению обработки в response вызывают внешнее действие в виде API-метода amo_next_action с полученным в качестве параметра json-параметром actions, таким образом можно последовательно вызывать связанные методы.

Описание методов

Авторизация

amo_access_token (post)

Служит для первичного обмен кода авторизации на access token и refresh token.

Код авторизации берем из настроек интеграции платформы в amoCRM

Последовательность действий администратора:

• из настроек интеграции на вкладке "Ключи и доступы" копируем ключ авторизации
• в базовых настройках в настройку amoPublicKey вставляем данный ключ авторизации
• запускаем данный метод API

В response данный метод в случае успешного получения токенов заносит в следующие базовые настройки полученные данные:

• amoAccessToken - полученный access token
• amoAccessTokenEnded - полученный срок окончания действия access token
• amoRefreshToken -полученный refresh token

В качестве параметра может использоваться actions: json с цепочкой последовательности действий. Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным json-параметром actions.

amo_refresh_token (post)

Поскольку срок существования  access token ограничен, то по мере истечения срока необходимо обновить его вызвав данный метод.

В response данный метод в случае успешного получения токенов заносит в следующие базовые настройки полученные данные:

• amoAccessToken - полученный access token
• amoAccessTokenEnded - полученный срок окончания действия access token
• amoRefreshToken -полученный refresh token

В качестве параметра может использоваться actions: json с цепочкой последовательности действий. Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным json-параметром actions.

Метод автоматически вызывается из метода API amo_next_action, если до окончания существования (берем из базовой настройки amoAccessTokenEnded) текущего access токена осталось менее минуты.

Получение данных

amo_account (get)

Метод обеспечивает получение данных аккаунта.

В response данный метод в случае успешного получения данных о текущем пользователе amoCrm заносит в следующие базовые настройки платформы полученные данные:

• amoUserID - полученный id текущего пользователя amoCrm

В качестве параметра может использоваться actions: json с цепочкой последовательности действий. Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным json-параметром actions.

Метод автоматически вызывается из метода API amo_next_action, если базовая настройка amoUserID пуста.

Создания/изменения сущностей

amo_create_contact (post)

Метод обеспечивает создание контакта в amoCrm на основании данных в нашей БД.

Параметры:

• userID - id пользователя в as_users
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID - ошибка.

Если в as_users для данного пользователя amoContactID пустой, то в amoCrm создается новый контакт, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в as_users для данного пользователя amoContactID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_contact (patch)

Метод обеспечивает изменение контакта в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID - ошибка.

Если в as_users для данного пользователя amoContactID пустой, то в amoCrm создается новый контакт, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в as_users для данного пользователя amoContactID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_company (post)

Метод обеспечивает создание компании в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID, или связанного с ним в xx_suppliers, или пользователь не имеет роли supplier  - ошибка.

Если в xx_suppliers для данного поставщика amoCompanyID пустой, то в amoCrm создается новая компания, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoCompanyID:

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_company (patch)

Метод обеспечивает изменение компании в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID, или связанного с ним в xx_suppliers, или пользователь не имеет роли supplier  - ошибка.

Если в xx_suppliers для данного поставщика amoCompanyID пустой, то в amoCrm создается новая компания, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoCompanyID:

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_product (post)

Метод обеспечивает создание продукта в amoCrm на основании данных платформы.

Параметры:

• courseID - id курса в xx_courses
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в xx_courses указанного courseID, или связанного с ним в xx_suppliers - ошибка.

Если в xx_courses для данного поставщика amoProductID пустой, то в amoCrm создается новый продукт, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в xx_courses для данного поставщика amoProductID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным

amo_modify_product (patch)

Метод обеспечивает изменение продукта в amoCrm на основании данных платформы.

Параметры:

• courseID - id курса в xx_courses
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в xx_courses указанного courseID, или связанного с ним в xx_suppliers - ошибка.

Если в xx_courses для данного поставщика amoProductID пустой, то в amoCrm создается новый продукт, иначе - изменяется.

Для определения синхронизации данных платформы и amoCrm используются таблицы xx_amoFields и xx_amoFieldValues.

В response данный метод в случае успешного завершения сохраняет в xx_courses для данного поставщика amoProductID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

Создания/изменения сделок

amo_create_deal_supplier (post)

Метод обеспечивает создание на базе поставщика курсов сделки в воронке "Поставщики" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions

amo_modify_deal_supplier (patch)

Метод обеспечивает изменение на базе поставщика курсов сделки в воронке "Поставщики" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_deal_product (post)

Метод обеспечивает создание на базе курса поставщика сделки в воронке "Создание продукта" в amoCrm на основании данных платформы.

Параметры:

• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID  или курс с указанным courseID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_courses для данного поставщика amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_deal_product (patch)

Метод обеспечивает изменение на базе курса поставщика сделки в воронке "Создание продукта" в amoCrm на основании данных платформы.

Параметры:

• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID  или курс с указанным courseID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_courses для данного поставщика amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_deal_srs (post)

Метод обеспечивает создание на базе поставщика курсов сделки в воронке "CPC расчет по поставщикам" в amoCrm на основании данных платформы если указан тип сотрудничества - CPC.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoSrsDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_deal_srs (patch)

Метод обеспечивает изменение на базе поставщика курсов сделки в воронке "CPC расчет по поставщикам" в amoCrm на основании данных платформы если указан тип сотрудничества - CPC.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит поставщика курсов с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_suppliers для данного поставщика amoSrsDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_deal_student (post)

Метод обеспечивает создание на базе клиента сделки в воронке "Учащиеся" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит кликета с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_clients для данного клиента amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_deal_student (patch)

Метод обеспечивает изменение на базе клиента сделки в воронке "Учащиеся" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• courseID - id курса - в данном методе не используется, для унификации вызова
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит кликета с указанным userID - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_clients для данного клиента amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_create_deal_course (post)

Метод обеспечивает создание на базе курса клиента сделки в воронке "Прохождение курсов" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users (здесь userID - клиента, проходящего курс)
• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит клиента с указанным userID или курса courseID у него - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_orderCourses для данного курса клиента amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

amo_modify_deal_course (patch)

Метод обеспечивает изменение на базе курса клиента сделки в воронке "Прохождение курсов" в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users (здесь userID - клиента, проходящего курс)
• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит клиента с указанным userID или курса courseID у него - ошибка.

В response данный метод в случае успешного завершения сохраняет в xx_orderCourses для данного курса клиента amoDealID.

Если actions не пустой, то в response данного метода будет вызвано внешнее действие в виде API-метода amo_next_action с данным actions.

Сервисные

amo_next_action

Метод обеспечивает наличие токенов авторизации, текущего юзера amoCrm и вызова следующего API-метода в цепочке действий.

Параметры:

• actions - json с цепочкой последовательности дальнейших действий

Метод использует в качестве url псево-метод API amo_xxxxx_next платформы.

Если метод не находит в actions следующего действия - ошибка и выполнение цепочки прерывается.

Если же actions не пустой, то метод проверяет срок действия access токена и, в случае остатка его действия менее минуты, вызывает API-метод amo_refresh_token с actions в качестве параметра.

Затем метод проверяет, что базовая настройка платформы amoUserID не пустая, в противном случае вызывается API-метод amo_account с actions в качестве параметра.

Если же токены рабочие и текущий юзер amoCrm определен, то в response первое действие в цепочке удаляется из цепочки и вызывается как внешние API-действие, при этом десятым параметром является оставшаяся цепочка actions.

Структура actions (10-й параметр зарезервирован для передачи actions по цепочке):

[

{ "code":"code метода API", "p1_name":"название параметра", "p1_value":"значение параметра", ... , "p9_name":"название параметра", "p9_value":"значение параметра" }

, ...

]

Например, необходимо создать/изменить в amoCrm контакт и, возможно, связанного с ним клиента и/или компании-поставщика:

[

 { "code":"amo_modify_contact", "p1_name":"userID", "p1_value":1135 }

,{ "code":"amo_modify_client", "p1_name":"userID", "p1_value":1135 }

,{ "code":"amo_modify_company", "p1_name":"userID", "p1_value":1135 }

]

amo_xxxxx_next

псевдо-метод пустого обращения платформы сама к себе для построения цепочек запросов к amoCrm

Агрегатные

amo_modify_user

Метод обеспечивает создание/изменение любого пользователя в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя в as_users
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID - ошибка.

В response данный метод в случае успешного завершения формирует необходимую цепочку вызовов методов API для изменения данных о пользователе в зависимости от его ролей и вызывает через внешние действие amo_next_action с сфомированной цепочкой.

amo_modify_course

Метод обеспечивает создание/изменение курса в amoCrm на основании данных платформы.

Параметры:

• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в xx_courses указанного courseID - ошибка.

В response данный метод в случае успешного завершения формирует необходимую цепочку вызовов методов API для изменения данных о курсе и вызывает через внешние действие amo_next_action с сфомированной цепочкой.

amo_modify_usercourse

Метод обеспечивает создание/изменение сделок прохождения курса в amoCrm на основании данных платформы.

Параметры:

• userID - id пользователя, проходящего данный курс
• courseID - id курса
• actions - json с цепочкой последовательности дальнейших действий

Если метод не находит в as_users указанного userID или в xx_courses указанного courseID - ошибка.

В response данный метод в случае успешного завершения формирует необходимую цепочку вызовов методов API для изменения данных о курсе и вызывает через внешние действие amo_next_action с сфомированной цепочкой.