WT Amo CRM library

Описание

Пакет представляет собой набор расширений для удобной работы с REST API AmoCRM в Joomla. Библиотека не требует установки никаких дополнительных программных пакетов (зависимостей), использует только API Joomla. Код библиотеки документирован и IDE (профессиональные среды разработки) будут показывать подсказки по кодовой базе.

Эта библиотека в чистом виде будет интересна скорее всего только профессиональным разработчикам и интеграторам.

В составе пакета:

• библиотека интеграции Joomla и AmoCRM: WT Amo CRM Library
• плагин хранения настроек для подключения к AmoCRM: Система - WT Amo CRM Library
• плагин для синхронизации данных контактов AmoCRM и пользователей Joomla: Пользователь - WT AmoCRM user synс.
• плагин для CLI Joomla (команды консоли сервера) для добавления команд в CLI Joomla: Консоль - WT import AmoCRM contacts.

Авторизация библиотеки в REST API AmoCRM

Для хранения данных авторизации в AmoCRM служит плагин Система - WT Amo CRM Library. В нём вы указываете домен, секретный ключ, токен, ID интеграции и т.д. Библиотека получает данные из параметров плагина. Поддерживаются как обычные, так и долгоживущие (долгосрочные) токены. 

Удаление старого refresh token

Если вы используете обычные токены, а не долгосрочные, то Amo CRM выдаёт access-токен на одни сутки. Для получения нового токена используется refresh-токен. Refresh токен действует всего 3 месяца. Если интеграция не используется в течение 3 месяцев, не было ни одного запроса на актуализацию ключа, то интеграция потеряет доступ к данным и будем необходимо повторно создавать и настраивать интеграцию.

Для упрощения этого процесса в параметры плагина добавлена кнопка удаления старого refresh-токен из базы данных. Если refresh-токен есть в базе данных - отображается дата его получения.

Подключение библиотеки в своё расширение для Joomla

use Webtolk\Amocrm\Amocrm;

$amocrm = new Amocrm();
$accountData = $amocrm->account()->getAccountInfo();
// Joomla uses a Symfony vardumper
dump($accountData);

Список сущностей AmoCRM для работы из Joomla

PHP-классы поддерживаемых сущностей находятся в папке src/Entities.

1. \Webtolk\Amocrm\Entities\Account $amocrm->account() - получение информации об аккаунте
2. \Webtolk\Amocrm\Entities\Contacts $amocrm->contacts() - работа с сущностью контактов AmoCRM
3. \Webtolk\Amocrm\Entities\Customfields $amocrm->customfields() - работа с кастомными полями сущностей AmoCRM
4. \Webtolk\Amocrm\Entities\Leads $amocrm->leads() - работа с сущностью сделок AmoCRM
5. \Webtolk\Amocrm\Entities\Notes $amocrm->notes() - работа с примечаниями к сущностям AmoCRM
6. \Webtolk\Amocrm\Entities\Tags $amocrm->tags() - работа с сущностью тегов AmoCRM
7. \Webtolk\Amocrm\Entities\Users $amocrm->users() - работа с сущностью пользователей AmoCRM
8. \Webtolk\Amocrm\Entities\Webhooks $amocrm->webhooks() - работа с вебхуками AmoCRM

Синхронизация пользователей Joomla и AmoCRM. Двухсторонняя интеграция.

Плагин Пользователь - WT AmoCRM user synс в поставке библиотеки позволяет как создавать новые контакты в AmoCRM при создании / регистрации пользователей в Joomla, так и создавать пользователей Joomla при создании контактов AmoCRM. Возможно обновлять информацию в одной системе при изменении данных в другой. Настройки сопоставления полей Joomla и AmoCRM. Данные также можно хранить в свойстве params объекта пользователя ($user->params). Сопоставление полей настраивается в параметрах плагина.

CLI плагин импорта пользователей Joomla из контактов AmoCRM.

В AmoCRM есть экспорт данных в CSV. Однако, возможно из-за большого количества разного рода интеграций, данные не всегда корректно экспортируются. Дабы избежать проблем с нарушением структуры данных было принято решение сделать более медленный импорт данных напрямую по REST API. Команды для выполнения в консоли сервера можно увидеть в параметрах плагина группы console.

Обработка входящих вебхуков AmoCRM в Joomla.

В системном плагине добавлена единая точка входа для вебхуков со стороны AmoCRM. В дальнейшем информация из вебхука передаётся плагинам групп system, user и amocrm, срабатывающим на событие onAmocrmIncomingWebhook. Вы можете создать собственный плагин, который будет слушать это событие и обрабатывать данные или выполнять некие действия на стороне Joomla при событиях в AmoCRM.

Коллекция полей Joomla Form с данными из AmoCRM для разработчиков.

Для использования в расширениях Joomla создана коллекция полей Joomla Form. Эти поля используются в плагинах самой библиотеки, однако разработчики могут использовать готовые поля и в сторонних расширениях. Классы полей находятся в папке src/Fields библиотеки. Для корректной работы поля необходимо в XML-манифесте вашего расширения (плагин, модуль, компонент) указать атрибут addfieldprefix с неймспейсом библиотеки.

<field addfieldprefix="Webtolk\Amocrm\Fields"
                       type="accountinfo"
                       name="accountinfo"/>

Список полей на текущий момент:

• Accountinfo - поле с информацией об аккаунте AmoCRM
• Companiestagslist - выпадающий список тегов компаний AmoCRM
• Companycustomfieldslist - выпадающий список пользовательских полей компаний AmoCRM
• Contactcustomfieldslist - выпадающий список пользовательских полей контактов AmoCRM
• Contactinfo - информация о контакте и ссылка на него в AmoCRM
• Contactstagslist - выпадающий список тегов контактов AmoCRM
• Entitymodalselect - модальное (всплывающее) окно для выбора id сущности: сделки или контакта.
• Leadcustomfieldslist - выпадающий список пользовательских полей сделки AmoCRM
• Leadspipelineslist - выпадающий список воронок AmoCRM
• Leadstagslist - выпадающий список тегов сделок AmoCRM
• Webhookslist - информация о вебхуках аккаунта AmoCRM и их ограничениях.

Поля реализованы с использованием layouts Joomla. При острой необходимости вы можете переопределить макет вывода поля штатными средствами Joomla.

Группа плагинов amocrm для разработчиков

Чтобы гибкие и сложные интеграции не влияли скорость работы сайта - добавлена специализированная группа для плагинов - amocrm. Вы можете создать собственный плагин этой группы и работать с данными AmoCRM не затрагивая остальные разделы Joomla.