Обёртка для простого взаимодействия с Api AmoCRM
Подключение
Перед использованием обёртки, нужно подключить файл автозагрузки классов 'autoload.php'.
Путь к файлу конечно же может отличаться от примера ниже. Или вы можете включать этот компонент в свой автозагрузчик.
<?php require_once 'AmoCRM_Wrap/autoload.php'; ?>
Использование
Для начала нужно произвести авторизацию. Для этого создаётся экземпляр класса AmoCRM в конструктор которого необходимо
передать:
- Субдомен црм
- Логин юзера(почта)
- API ключ пользователя. Его вы можете найти в интерфейсе црм https://test.amocrm.ru/settings/profile/
- 'test' нужно заменить на свой поддомен
Так как в обёртке предусмотрены Исключения (Exception) которые вызываются в случаях всевозможных ошибок, то их
необходимо олавливать т.е. весь код работы с обёрткой следует помещать в try catch.
Пример авторизации:
<?php
try {
$amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', '[email protected]', '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 - путь до файла
Все методы базовые
Класс 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', '[email protected]', '011c2d7f862c688286b43ef552fb17f4');
$contacts = $amo->searchContactsByPhoneAndEmail('79998887766', '[email protected]'); //Ищем контакт по телефону и почте
$contact = current($contacts); //Берём первый найденый контакт
$contact->setName("{$contact->getName()} лучший") //Меняем имя дописывая в текущее строчку
->addPhone('78889998887766', 'MOB') //Добавляем мобильный телефон
->addEmail('[email protected]', 'WORK') //Добавляем рабочую почту
->delEmail('[email protected]') //Удаляем почту
->setResponsibleUser('Пётр Иванович') //Меняем ответственного
->save() //Сохраняем все изменение на сервере црм
->addTask('Позвонить клиенту', 'Саша'); //Прикрепляем задачку, и назначаем ответственным за неё Сашу
} catch (\DrillCoder\AmoCRM_Wrap\AmoWrapException $e) {
die($e->getMessage()); //Прерывем работу скрипта и выводим текст ошибки
}
?>
Создание сделки с примечанием и двумя привязанными контактами в "Неразобранном" в вороке "Вторые продажи"
<?php
try {
$amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', '[email protected]', '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 = '[email protected]';
$responsibleUserId = 'Александр';
$comment = 'Срочно перезвонить!';
try {
$amo = new \DrillCoder\AmoCRM_Wrap\AmoCRM('test', '[email protected]', '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();
}?>