WT AmoCRM library (Joomla) — Core API

Документация по базовым классам библиотеки Webtolk\Amocrm из lib_webtolk_amocrm/src.

Быстрый старт (рекомендуемый путь)

use Webtolk\Amocrm\Amocrm;

$amocrm = new Amocrm();

// Получить список сделок
$leads = $amocrm->leads()->getLeads(['limit' => 50]);

// Получить контакт по ID
$contact = $amocrm->contacts()->getContactById(123456);

Требования:

• Включён системный плагин System - WT AmoCRM.
• В параметрах плагина заполнены amocrm_domain, amocrm_client_id, amocrm_client_secret и (для OAuth) amocrm_code.
• Для webhook/компонента AJAX используется com_ajax.

Класс Amocrm

Фасад библиотеки. В 1.3.0+ основной путь — доступ к сущностям через магический __call(): $amocrm->leads(), $amocrm->contacts(), $amocrm->users() и т.д.

Большинство методов в классе помечены как deprecated (1.3.0) и сохранены для обратной совместимости. Используйте Entity-классы через __call() и AmocrmRequest.

Ключевые методы

• __construct() — загружает языковые файлы библиотеки и инициализирует AmocrmRequest.
• getRequest(): AmocrmRequest — получить объект запроса (рекомендуется для низкоуровневых вызовов).
• __call(string $name, array $_): EntityInterface — возвращает экземпляр сущности из Webtolk\Amocrm\Entities.

Deprecated-методы (1.3.0, будут удалены в 2.0)

Используйте аналоги из Entity-классов:

• getAccountInfo() > account()->getAccountInfo()
• getLeadById() > leads()->getLeadById()
• createLeads() > leads()->createLeads()
• createLeadsComplex() > leads()->createLeadsComplex()
• getTags() > tags()->getTags()
• getLeadsPiplines() > leads()->getLeadsPiplines()
• getCustomFields() > customfields()->getCustomFields()
• getContactsCustomFields() > customfields()->getContactsCustomFields()
• getCompaniesCustomFields() > customfields()->getCompaniesCustomFields()
• getCustomersCustomFields() > customfields()->getCustomersCustomFields()
• getContacts() > contacts()->getContacts()
• addContacts() > contacts()->addContacts()
• getUserById() > users()->getUserById()
• getNotes() > notes()->getNotes()
• addNotes() > notes()->addNotes()

Также устарели собственные методы управления токенами (authorize, setToken, storeTokenData и т.д.).

Класс AmocrmRequest

Низкоуровневый HTTP-клиент с логикой авторизации, кэша токена и обработки ошибок.

Основные методы

• getResponse(string $endpoint, ?array $data, string $request_method = 'POST', string $content_type = 'application/x-www-form-urlencoded', bool $custom_endpoint = false): object 
  • Делает REST-вызов к AmoCRM.
  • Если $custom_endpoint = true, путь берётся «как есть» (без /api/v4).
  • Возвращает объект ответа или объект ошибки { error_code, error_message }.

• canDoRequest(): bool - Проверяет наличие параметров подключения и токена.

• getPluginParams(): Registry - Читает параметры плагина system/wt_amocrm.

• getAmoCRMHost(): Uri - Возвращает Uri для домена AmoCRM (с принудительным https).

• Методы управления токеном: setToken(), setTokenType(), setTokenExpiresIn()
  • storeTokenData() — сохраняет токен в Joomla Cache.
  • storeRefreshToken() — сохраняет refresh token в параметры библиотеки.

Особенности

• Поддержка режима token_type = long_term (берёт токен из параметра long_term_token).
• Опциональное замедление запросов при avoid_rest_api_limits_exceeding = 1 (usleep 150ms).
• Ошибки логируются в lib_webtolk_amo_crm.log.php.

Пример низкоуровневого вызова

use Webtolk\Amocrm\Amocrm;

$amocrm = new Amocrm();
$request = $amocrm->getRequest();

// Получить аккаунт
$account = $request->getResponse('/account', null, 'GET', 'application/json');

Exceptions

• AmocrmException — общий exception библиотеки.
• AmocrmClientException — deprecated (1.3.0).

Traits

• LogTrait - saveToLog(string $data, string $priority = 'NOTICE', string $log_name = 'lib_webtolk_amo_crm') - Пишет в logs/{log_name}.log.php, показывает сообщение в админке.
• DataErrorTrait 
  • receivedEmptyData() — формирует типовой error-объект. 
  • wrongEntityType() — формирует error-объект при неверном типе сущности.

Интерфейс EntityInterface

Минимальный контракт: конструктор принимает AmocrmRequest.

public function __construct(AmocrmRequest $request);