Skip to content

✅ Обёртка для простого взаимодействия с Api AmoCRM

License

Notifications You must be signed in to change notification settings

drillcoder/AmoCRM_Wrap

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

64 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Обёртка для простого взаимодействия с Api AmoCRM

Build Status Latest Stable Version Total Downloads License

Подключение

Перед использованием обёртки, нужно подключить файл автозагрузки классов 'autoload.php'. Путь к файлу конечно же может отличаться от примера ниже. Или вы можете включать этот компонент в свой автозагрузчик.

<?php require_once 'AmoCRM_Wrap/autoload.php'; ?>

Использование

Для начала нужно произвести авторизацию. Для этого создаётся экземпляр класса AmoCRM в конструктор которого необходимо передать:

  1. Субдомен црм
  2. Логин юзера(почта)
  3. API ключ пользователя. Его вы можете найти в интерфейсе црм https://test.amocrm.ru/settings/profile/
  • 'test' нужно заменить на свой поддомен

Так как в обёртке предусмотрены Исключения (Exception) которые вызываются в случаях всевозможных ошибок, то их необходимо олавливать т.е. весь код работы с обёрткой следует помещать в try catch.

Пример авторизации:

<?php
try {
    $amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', 'test@test.ru', '011c2d7f862c688286b43ef552fb17f4');
    // ...
} catch (\DrillCoder\AmoCRM_Wrap\AmoWrapException $e) {
    die($e->getMessage());
}
?>

Возможности

  • Создание полного бэкапа црм, даже при отсутствии такой опции в тарифе
  • Поиск контакта по телефону или почте. Даный метод можно использовать для поиска дублей
  • Поиск по произвольному запросу среди Контактов, Компаний, Сделок, Примечаний и Задач
  • Получение списка любых сущностей с различной фильтрацией
  • Создание, изменение и удаление контактов, сделок, компаний, заметок и задач
  • Прикрепление к контактам, сделкам и компаниям файлов, заметок и задач
  • Удобная работа с доп полями, без знания их id
  • Назначение ответственных без id по имени или части имени пользователя в црм
  • На все запросы возвращается не огромный масив с данными, а удобные для работы объекты (Contact, Lead и тп)

В ближайших плана

  • Возможность развёртования бэкапа
  • Добавлени возможности работы с новыми сущностями (Покупатели и тп)
  • Добавление валидации к заданиям значений в пользовательским полям

Благодарности

  • Владислав Алаторцев — За уникальные методы прикрепления файлов и удаления сущностей а так же работе без возможности создания файла для хранения куки
  • Роман Маслеников — За поиски и исправление багов

Описание методов основных классов

Класс AmoCRM

  • AmoCRM::VERSION — Текущая версия обёртки
  • AmoCRM::getPhoneFieldId() — Возвращает id поля телефона у сущности Контакт
  • AmoCRM::getEmailFieldId() — Возвращает id поля почты у сущности Контакт
  • AmoCRM::getUsers() — Возвращает массив пользователей в црм
  • AmoCRM::getTaskTypes() — Возвращает массив типов задач
  • AmoCRM::getPipelinesName() — Возвращает массив воронок в црм
  • AmoCRM::getStatusesName($pipelineId) — Возвращает массив статусов в указанной воронке (нужен id воронки)
  • AmoCRM::getCustomFields($type) — Возвращает массив пользовательских полей у заданного типа сущности. Возможные типы: contact, lead, company
  • AmoCRM::getCustomFieldsEnums($type) — Возвращает массив enums пользовательских полей у заданного типа сущности
  • searchContactsByPhoneAndEmail($phone, $email) — Поиск по контактам без учета формата телефона. Телефоны начинающиеся с 7 или 8 считает разными. Возвращяет массив из объектов Contact, где ключи id контактов

Поиск по Контактам, Компаниям, Сделкам, Задачам и Примечаниям ко всем сущностям отдельно

  • searchContacts/searchCompanies/searchLeads/searchTasks
  • getContactNotes/getCompanyNotes/getLeadNotes/getTaskNotes ($query = null, $limit = 0,$offset = 0, $responsibleUsersIdOrName = array(), DateTime $modifiedSince = null, $isRaw = false) — Поиск по заданным сущностям. Все поля не обязательны. Если ничего не задано, то вернется полный список всех сущностей. $query - текст запроса. $limit - количество сущностей в ответе. 0 = без ограничения $offset - пропуск количества сущностей от начала $responsibleUsersIdOrName - ответственные юзеры (имя или id). Если несколько то в массиве $modifiedSince - измененный после даты и время заданным объектом DateTime $isRaw - флаг получить "сырые" данные. Массивом как при обычном запросе к апи

Важно!!! Все списки сортируются от самого ранее изменённого. Сортировку поменять нельзя =(

  • backup($directory) — Создаёт полный бэкап всей црм в директории $directory. Возможны проблемы с лимитом памяти

Абстрактный класс BaseEntity

На этом классе базируются все другие основные классы. Все методы присутствующие в нём можно использовать в других классах.

  • __construct($id = null) — Метод вызываемый при создании экземпляра класса. Можно передать id нужной сущность и тогда произойдёт загрузка данный из црм. Если не передавать id то будет создан пустой объект
  • getRaw() — Получить сырые данные на основе сущности
  • save() — Сохраняет текущую сущность в црм
  • delete() — Удаляет текущую сущность в црм
  • getId() — Возвращает id сущность
  • getName() — Возвращает имя сущности
  • setName($name) — Изменяет имя на $name
  • getResponsibleUserId() — Возвращает id ответственного за сущность
  • getResponsibleUserName() — Возвращает имя ответственного за сущность
  • setResponsibleUser($responsibleUserIdOrName) — Устанавливает ответственного за сущность. Принимает либо id ответственного либо его имя (ищет эту строку во всех именах всех менеджеров црм)
  • getDateCreate() — Возвращает объект DateTime с датой и временем создания сущность
  • getDateUpdate() — Возвращает объект DateTime с датой и временем последнего изменения сущность
  • getUserIdUpdate() — Возвращает id человека который последний раз изменял сущность
  • getUserNameUpdate() — Возвращает имя человека который последний раз изменял сущность
  • getCreatedUserId() — Возвращает id человека создавшего сущность
  • getCreatedUserName() — Возвращает имя человека создавшего сущность
  • getLeadsId() — Возвращает массив из id прикреплённых сделок
  • getLeads() — Возвращает массив объектов Lead прикреплённых сделок
  • addLead($lead) — Прикрепляет к сущность сделку
  • delLead($lead) — Открепляет сделку от сущность
  • getContactsId() — Возвращает массив из id прикреплённых контактов
  • getContacts() — Возвращает массив объектов Contact прикреплённых контактов
  • addContactId($contact) — Прикрепляет к сущность контакт
  • delContactId($contact) — Открепляет контакт от сущность
  • getCompanyId() — Возвращает id компании к которой привязана сущность
  • getCompany() — Возвращает объект Company компании к которой привязана сущность
  • setCompany($company) — Устанавливает компанию к которой будет привязана сущность
  • getTags() — Возвращает ассоциативный массив тэгов id => name
  • addTag($tag) — Добавляет тэг к сущности
  • delTag($tag) — Удаляет тэг у сущности
  • getPhones() — Возвращает нумерованый массив телефонов
  • addPhone($phone, $enum = CustomField::PHONE_OTHER) — Добавляет телефон к сущности, не обязательны пораметр тип телефона, по умолчанию "Другой". Проверяет имеется ли уже такой телефон у сущности и не добавляет дубликат. Возможные варианты типов телефона находятся в константах CustomField::PHONE__
  • delPhone($phone) — Удаляет телефон у сущности. Не учитывает формат телефона. Учитывает начинается телефон с 7 или 8
  • getEmails() — Возвращает нумерованый массив email'ов
  • addEmails($email, $enum = CustomField::EMAIL_OTHER) — Добавляет почту к сущности, не обязательны пораметр тип почты, по умолчанию "Другой". Проверяет имеется ли уже такая почта у контакт и не добавляет дубликат. Возможные варианты типов почт находятся в константах CustomField::Email_
  • delEmail($email) — Удаляет почту у сущности
  • addCustomField($name, $type = CustomField::TYPE_TEXT, $enums = array()) — Создаёт кастомное поле у текущего типа сущности с именем $name типом $type и если необходимо вариантами $enums. Возвращает id созданого поля. Типы полей храняться в CustomField::TYPE_
  • delCustomField($nameOrId) — Удаляет кастомное поле у текущего типа сущности, принимает как id поля так и его имя
  • getCustomFieldValueInStr($nameOrId) — Возвращает значение кастомного поля в виде строки. Принимает его имя или id. Разделитель значений точка с запятоу (;)
  • getCustomFieldValueInArray($nameOrId) — Возвращает значение кастомного поля в виде массива. Принимает его имя или id
  • setCustomFieldValue($customFieldNameOrId, $value, $subtype = null) — Задаёт значение кастомного поля. Первым аргументов можно передать как id поля, так и его название в црм. Если не передавать значение ($value) или задать его пустым, то при сохранении поле в црм так же будет очищено. В поле типа мультисписок значения вносятся массивом. Для типа адрес так же требуеться $subtype типы которого храняться в Value::SUBTYPE_
  • addNote($text) — Добавляет примичание для текущей сущности
  • addNoteSystem($text, $serviceName) — Добавляет системное(не удаляемое) примечание для текущей сущности
  • addNoteSmsOut($text, $phone) — Добавляет примечание для текущей сущности типа Исходящее смс (на номер $phone)
  • addNoteSmsIn($text, $phone) — Добавляет примечание для текущей сущности типа Входящее смс (с номера $phone)
  • addTask($text, $responsibleUserIdOrName = null, DateTime $completeTill = null, $typeId = 3) — Добавляет задачу для текущей сущности. $text - текст задачи. $responsibleUserIdOrName(не обязательный) - ответственный, принимает как id так и имя, если не установлен то ответственный тот же что и у текущей сущность. $completeTill(не обязательный) - дата и время, в виде объекта класса DateTime, до которого нужно завершить задачу, если не указан то время устанавливается текущее. $typeId(не обязательный) - тип задачи см. варианты в црм, если не установлен принимает тип 3 - письмо.
  • addFile($pathToFile) — прикрепляет файл к сущность (Сделка, Контакт или Компания). $pathToFile - путь до файла

Классы Contact и Company

Все методы базовые

Класс Lead

  • getSale() — Возвращает бюджет
  • setSale($sale) — Задаёт бюджет
  • getPipelineId() — Возвращает id воронки
  • getPipelineName() — Возвращает название воронки
  • getStatusId() — Возвращает id статуса
  • getStatusName() — Возвращает название статуса
  • setPipeline($idOrNamePipeline) — Задаёт воронку. Принимает id либо название
  • setStatus($idOrNameStatus, $idOrNamePipeline = null) — Задаёт статус в воронке $idOrNamePipeline, если не указано в текущей. Принимает id либо название из црм, как воронки так и статуса
  • getMainContactId() — Возвращает id основного контакта
  • getMainContact() — Возвращает объект Contact основного контакта
  • setMainContact($contact) — Задаёт основной контакт
  • isClosed() — Возвращает true если сделка закрыта и false в противном случае

Класс Note и Task

  • getElementId() — Возвращает id сущности к которой будет привязана заметка или задача
  • setElementId($elementId) — Задаёт id сущности к которой будет привязана заметка или задача
  • getElementType() — Возвращает тип сущности к которой будет привязана заметка или задача

Возможные значения: 1 - Контакт, 2 - Сделка, 3 - Компания, 4 - Результат задачи

  • setElementType($elementType) — Устанавливает тип сущности к которой будет привязана заметка или задача. Воможные варианты таке же как выше
  • getType() — Возвращает тип задачи или заметки
  • setType($type) — Задаёт тип задачи или заметки. Варианты см. в црм
  • getText() — Возвращает текст задачи или заметки
  • setText($text) — Задаёт текст задачи или заметки

Класс Unsorted

  • new Unsorted($formName, $lead, $contacts, $pipelineIdOrName = null, $companies = array()) — Создание объекта $formName - название формы которое будет отображаться в интерфейсе црм. $lead - сделка котороя будет создана после принятия заявки в "неразобранном". $contacts - массив объектов Contact которые будут созданы и привязаны к сделки после принятия заявки в "неразобранном". $pipelineIdOrName - Воронка в которой будет создана заявка, необязательный параметр. $companies - необязательный параметр, массив объектов Company которые будут созданы и привязаны к сделки после принятия заявки в "неразобранном"
  • addNote($text) — Добавляет текстовую заметку для сделки. Необходимо использовать перед сохранением
  • save() — Сохраняет "неразобранное" в црм

Классы хэлперы Config, CustomField, Value, Note и Task

Созданы как вспомогательные по этому описывать их не буду)

Примеры

Поиск, изменение и сохранение контакта в црм

<?php
try {
    $amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', 'test@test.ru', '011c2d7f862c688286b43ef552fb17f4');
    $contacts =  $amo->searchContactsByPhoneAndEmail('79998887766', 'test@test.ru'); //Ищем контакт по телефону и почте
    $contact = current($contacts); //Берём первый найденый контакт
    $contact->setName("{$contact->getName()} лучший") //Меняем имя дописывая в текущее строчку
            ->addPhone('78889998887766', 'MOB') //Добавляем мобильный телефон
            ->addEmail('test2@test.ru', 'WORK') //Добавляем рабочую почту
            ->delEmail('test@test.ru') //Удаляем почту
            ->setResponsibleUser('Пётр Иванович') //Меняем ответственного
            ->save() //Сохраняем все изменение на сервере црм
            ->addTask('Позвонить клиенту', 'Саша'); //Прикрепляем задачку, и назначаем ответственным за неё Сашу
} catch (\DrillCoder\AmoCRM_Wrap\AmoWrapException $e) {
    die($e->getMessage()); //Прерывем работу скрипта и выводим текст ошибки
}
?>

Создание сделки с примечанием и двумя привязанными контактами в "Неразобранном" в вороке "Вторые продажи"

<?php
try {
    $amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', 'test@test.ru', '011c2d7f862c688286b43ef552fb17f4');
    $contact = new \DrillCoder\AmoCRM_Wrap\Contact();
    $contact->setName('Петя')
            ->addPhone(79998887766); //Создаём контакт, который будет создан в црм после принятия заявки в неразобранном
    $contact2 = new \DrillCoder\AmoCRM_Wrap\Contact();
    $contact2->setName('Ваня')
             ->addPhone(79998887755); //Создаём второй контакт
    $lead = new \DrillCoder\AmoCRM_Wrap\Lead();
    $lead->setName('Тестовая сделка')
         ->setSale(2500); //Создаём сделку, которая будет создана в црм после принятия заявки в неразобранном
    $unsorted = new \DrillCoder\AmoCRM_Wrap\Unsorted('Супер-Форма', $lead, array($contact, $contact2), 'Вторые продажи');
    $unsorted->addNote('Клиент сложный')
             ->save(); // Сохраняем всё в неразобранное в црм
} catch (\DrillCoder\AmoCRM_Wrap\AmoWrapException $e) {
    die($e->getMessage()); //Прерывем работу скрипта и выводим текст ошибки
}
?>

Реализация стандартной логики интеграции Ройстат и AmoCRM

Плюсом небольшая фишка с дозаполнением данными контакта

<?php
//Тестовые данные
$form = 'Заказать звонок';
$name = 'Тест';
$phone = '+7(999)888-77-66';
$email = 'testik@test.ru';
$responsibleUserId = 'Александр';
$comment = 'Срочно перезвонить!';

try {
    $amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', 'test@test.com', '8a66666666b3494179da07abc74bfd49');
    $lead = new \DrillCoder\AmoCRM_Wrap\Lead();
    $lead->setName("Заявка с формы '$form'")
         ->setCustomFieldValue('roistat', isset($_COOKIE['roistat_visit']) ? $_COOKIE['roistat_visit'] : null)
         ->setCustomFieldValue('roistat-marker', isset($_COOKIE['roistat_marker']) ? $_COOKIE['roistat_marker'] : 'Прямой визит')
         ->setCustomFieldValue('Форма захвата', $form)
         ->setCustomFieldValue('utm_source', $_COOKIE['utm_source'])
         ->setCustomFieldValue('utm_medium', $_COOKIE['utm_medium'])
         ->setCustomFieldValue('utm_campaign', $_COOKIE['utm_campaign'])
         ->setCustomFieldValue('utm_term', $_COOKIE['utm_term'])
         ->setCustomFieldValue('utm_content', $_COOKIE['utm_content'])
         ->setResponsibleUser($responsibleUserId)
         ->save()
         ->addNote($comment);
    $contacts = $amo->searchContactsByPhoneAndEmail($phone, $email);
    if (!empty($contacts)) {
        $contact = current($contacts);
    } else {
        $contact = new \DrillCoder\AmoCRM_Wrap\Contact();
        $contact->setName($name);
    }
    $contact->addPhone($phone)
            ->addEmail($email)
            ->addLead($lead)
            ->save();
} catch (\DrillCoder\AmoCRM_Wrap\AmoWrapException $e) {
    echo $e->getMessage();
}?>