Клиент для работы с API amoCRM

Клиент для работы с API сервиса amoCRM

Установка

Через composer:

$ composer require dotzero/amocrm

или добавить

"dotzero/amocrm": ">=0.3.0"

в секцию require файла composer.json.

Быстрый старт

try {
    // Создание клиента
    $amo = new \AmoCRM\Client('SUBDOMAIN', 'LOGIN', 'HASH');

    // Получение экземпляра модели для работы с аккаунтом
    $account = $amo->account;

    // Вывод информации об аккаунте
    print_r($account->apiCurrent());

    // Получение экземпляра модели для работы с контактами
    $contact = $amo->contact;

    // Заполнение полей модели
    $contact['name'] = 'ФИО';
    $contact['request_id'] = '123456789';
    $contact['date_create'] = '-2 DAYS';
    $contact['responsible_user_id'] = 697344;
    $contact['company_name'] = 'ООО Тестовая компания';
    $contact['tags'] = ['тест1', 'тест2'];

    // Добавление кастомного поля
    $contact->addCustomField(100, 'Значение');

    // Добавление кастомного поля с типом "мультисписок"
    $contact->addCustomMultiField(200, [
        1237755,
        1237757
    ]);

    // Добавление ENUM кастомного поля
    $contact->addCustomField(300, '+79261112233', 'WORK');

    // Добавление кастомного поля c SUBTYPE поля
    $contact->addCustomField(300, '+79261112233', false, 'subtype');

    // Добавление ENUM кастомного поля с типом "мультисписок"
    $contact->addCustomField(400, [
        ['+79261112233', 'WORK'],
    ]);

    // Добавление нового контакта и получение его ID
    print_r($contact->apiAdd());

} catch (\AmoCRM\Exception $e) {
    printf('Error (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Список доступных моделей

• Account (документация)
• Contact (документация)
• Lead (документация)
• Company (документация)
• Task (документация)
• Note (документация)

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

• Модель account для работы с Аккаунтом

  • apiCurrent($short = false) - Получение информации по аккаунту в котором произведена авторизация

• Модель contact для работы с Контактами

  • apiList($parameters, $modified = null) - Метод для получения списка контактов с возможностью фильтрации и постраничной выборки
  • apiAdd($contacts = []) - Метод позволяет добавлять контакты по одному или пакетно
  • apiUpdate($id, $modified = 'now') - Метод позволяет обновлять данные по уже существующим контактам
  • apiLinks($parameters, $modified = null) - Метод для получения списка связей между сделками и контактами

• Модель company для работы с Компаниями

  • apiList($parameters, $modified = null) - Метод для получения списка компаний с возможностью фильтрации и постраничной выборки
  • apiAdd($companies = []) - Метод позволяет добавлять компании по одной или пакетно
  • apiUpdate($id, $modified = 'now') - Метод позволяет обновлять данные по уже существующим компаниям

• Модель lead для работы со Сделками

  • apiList($parameters, $modified = null) - Метод для получения списка сделок с возможностью фильтрации и постраничной выборки
  • apiAdd($leads = []) - Метод позволяет добавлять сделки по одной или пакетно
  • apiUpdate($id, $modified = 'now') - Метод позволяет обновлять данные по уже существующим сделкам

• Модель note для работы с Примечаниями (Задачами)

  • apiList($parameters, $modified = null) - Метод для получения списка примечаний с возможностью фильтрации и постраничной выборки
  • apiAdd($notes = []) - Метод позволяет добавлять примечание по одному или пакетно
  • apiUpdate($id, $modified = 'now') - Метод позволяет обновлять данные по уже существующим примечаниям

• Модель task для работы с Задачами

  • apiList($parameters, $modified = null) - Метод для получения списка задач с возможностью фильтрации и постраничной выборки
  • apiAdd($tasks = []) - Метод позволяет добавлять задачи по одной или пакетно
  • apiUpdate($id, $text, $modified = 'now') - Метод позволяет обновлять данные по уже существующим задачам

Описание хелпера Fields

Для хранения ID полей можно воспользоваться хелпером Fields

try {
    $amo = new \AmoCRM\Client(getenv('DOMAIN'), getenv('LOGIN'), getenv('HASH'));

    // Для хранения ID полей можно воспользоваться хелпером \AmoCRM\Helpers\Fields
    $amo->fields->StatusId = 10525225;
    $amo->fields->ResponsibleUserId = 697344;

    // Добавление сделок с использованием хелпера
    $lead = $amo->lead;
    $lead['name'] = 'Тестовая сделка';
    $lead['status_id'] = $amo->fields->StatusId;
    $lead['price'] = 3000;
    $lead['responsible_user_id'] = $amo->fields->ResponsibleUserId;
    $lead->apiAdd();

    // Также можно просто использовать хелпер без клиента
    $fields = new \AmoCRM\Helpers\Fields();

    // Как объект
    $fields->StatusId = 10525225;
    $fields->ResponsibleUserId = 697344;

    // Или как массив
    $fields['StatusId'] = 10525225;
    $fields['ResponsibleUserId'] = 697344;

} catch (\AmoCRM\Exception $e) {
    printf('Error (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Описание хелпера B2BFamily

Хелпер для отправки письма через B2BFamily с привязкой к сделке в amoCRM

try {
    $amo = new \AmoCRM\Client(getenv('DOMAIN'), getenv('LOGIN'), getenv('HASH'));

    $b2b = new \AmoCRM\Helpers\B2BFamily(
        $amo,
        getenv('B2B_APPKEY'),
        getenv('B2B_SECRET'),
        getenv('B2B_EMAIL'),
        getenv('B2B_PASSWORD')
    );

    // Подписать клиента AmoCrm на Webhooks
    $b2b->subscribe();

    // Отправить письмо и прикрепить его к сделке
    $b2b->mail(6003277, [
        'to' => '[email protected]',
        'type' => 'message',
        'subject' => 'Тест b2bfamily',
        'text' => 'Тестовое сообщение',
        'events' => [
            'trigger' => 'message_open',
            'not_open_timeout' => 1
        ]
    ]);

} catch (\AmoCRM\Helpers\B2BFamilyException $e) {
    printf('Error (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Webhooks

WebHooks – это уведомление сторонних приложений посредством отправки уведомлений о событиях, произошедших в amoCRM. Вы можете настроить HTTP адреса ваших приложений и связанные с ними рабочие правила в настройках своего аккаунта, в разделе «API».

Список доступных уведомлений

• Контакты

  • contacts-add - Создание контакта
  • contacts-update - Изменение контакта
  • contacts-delete - Удаление контакта

• Компании

  • companies-add - Создание компании
  • companies-update - Изменение компании
  • companies-delete - Удаление компании

• Сделки

  • leads-add - Создание сделки
  • leads-update - Изменение сделки
  • leads-delete - Удаление сделки
  • leads-status - Смена статуса сделки
  • leads-responsible - Смена ответственного сделки

Обратите внимание, что при смене статуса сделки или при смене ответственного сделки, AmoCRM одновременно посылает информацию и об общем изменении сделки, то есть код для leads-status и leads-responsible всегда будет выполняться вместе с leads-update.

try {
    $listener = new \AmoCRM\Webhooks();

    // Добавление обработчка на уведомление contacts->add
    $listener->on('contacts-add', function ($domain, $id, $data) {
        // $domain Поддомен amoCRM
        // $id Id объекта связаного с уведомленим
        // $data Поля возвращаемые уведомлением
    });

    // Вызов обработчика уведомлений
    $listener->listen();

} catch (\AmoCRM\Exception $e) {
    printf('Error (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Интеграция с фреймворками

• Yii Framework 1.x (yii-amocrm)
• Yii Framework 2.x (yii2-amocrm)
• Laravel 5.x (laravel-amocrm)

Тестирование

Для начала установить --dev зависимости. После чего запустить:

$ vendor/bin/phpunit

Лицензия

Библиотека доступна на условиях лицензии MIT: http://www.opensource.org/licenses/mit-license.php