amo crm api php
Amo crm api php
Клиент для работы с API amoCRM
Удобный и быстрый клиент на PHP для работы с API amoCRM, реализующий все методы оригинального API.
Внимание! Не актуальные ссылки на документацию
Данный пакет взаимодействует со старой версией API. Но это не значит, что это API более не поддерживается. Это полностью рабочее API, которое не собираются удалять, просто ссылки более не актуальные, к сожалению на данный момент единственным решением будет просмотр документации тут:
Переход на новую версию API не быстрый и займет много времени.
в секцию require файла composer.json.
Без использования composer:
Скачать последнюю версию amocrm.phar.
Список поддерживаемых моделей
Описание методов моделей
Модель account для работы с Аккаунтом
Модель contact для работы с Контактами
Модель lead для работы со Сделками
Модель company для работы с Компаниями
Модель customer для работы с Покупателями
Модель transaction для работы с Транзакциями
Модель task для работы с Задачами
Модель note для работы с Примечаниями (Задачами)
Модель custom_field для работы с Дополнительными полями
Модель call для работы со Звонками
Модель unsorted для работы со Списком неразобранных заявок
Модель webhooks для работы с Webhooks
Модель pipelines для работы с Списком воронок и этапов продаж
Модель customers_periods для работы с Компаниями
Модель widgets для работы с Виджетами
Модель catalog для работы с Каталогами
Модель catalog_element для работы с Элементами каталога
Модель links для работы со Связями между сущностями
Описание работы с Webhooks
Webhooks – это уведомление сторонних приложений посредством отправки уведомлений о событиях, произошедших в amoCRM. Вы можете настроить HTTP адреса ваших приложений и связанные с ними рабочие правила в настройках своего аккаунта, в разделе «API».
Список доступных уведомлений
Описание хелпера Fields
Для хранения ID полей можно воспользоваться хелпером Fields
Описание хелпера B2BFamily
Хелпер для отправки письма через B2BFamily с привязкой к сделке в amoCRM
Интеграция с фреймворками
Amo crm api php
Внимание! code и secret_key виджета должны быть идентичны в загруженном архиве и создаваемом далее manifest.json на сервере. После этого можно создать index файл, который будет содержать базовые настройки и подключение библиотеки.
Теперь, необходимо создать папку /widget/ в которой будет происходить разработка виджета. В ней создаем всю структуру виджета и дополнительные файлы.
Файл /widget/widget.php
Файл /widget/widget.php должен содержать в себе класс Widget, который наследует системный класс \Helpers\Widgets.
Класс Widget должен содержать в себе методы, которые выполняют роль точек входа в виджет. Эти методы должны иметь уровень доступа строже, чем public (т.е. protected и/ или private). Точка входа должна иметь название, начинающееся с префикса endpoint_, например: endpoint_get().
CONTROLLER так же может иметь значение builder. В этом случае METHOD и ENDPOINT указывать не нужно. Обращение к контроллеру builder соберет наш виджет для работы с контроллером loader и создаст zip архив для загрузки на amoCRM.
При первом обращении к контроллеру loader и после каждого изменения в файлах виджета необходимо вызывать контроллер builder. Или установить значение константы AUTO_BUILD как true (описано выше)
Так же, следует помнить, что для работы с сервером amoCRM при обращении к точке входа должны передаваться amouser и amohash. Их можно посмотреть в настройке профиля пользователя в системе (/settings/profile/). Поле amouser – E-Mail пользователя, amohash – ключ для авторизации в API.
Библиотека для работы с виджетами позволяет напрямую взаимодействовать с системой с помощью точек входа (смотрите выше). Для примера создадим виджет, добавляющий контакт в amoCRM.
Особенности и ограничения библиотеки
Для отправки cURL запросов на сторонний сервис можно использовать встроенный класс
\Helpers\Curl::init($url,[$post=FALSE],[$cookie=FALSE]);
где:
$url — ссылка, куда отправляется запрос,
$post — массив для передачи (если он заполнен, то запрос будет отправлен по методу POST),
$cookie — TRUE/FALSE использовать ли куки-файл или нет
Любые приходящие из GET или POST параметры нужно получать через
\Helpers\Route::param(#ELEMENT_KEY#)
Метод \Helpers\Route::param(#ELEMENT_KEY#) так же доступен как $this->param(#ELEMENT_KEY#)
Получение настроек текущего виджета в amoCRM возможно путем вызова
$this->account->current(‘widget’);
Для работы с языковыми сообщениями можно использовать встроенный класс
\Helpers\I18n::get(‘settings.enums.yes’)
Все языковые сообщения должны быть описаны в директории /widget/i18n/#lang#.json
Создание собственной Web-странички
На примере ниже мы продемонстрируем создание простой html-формы для добавления контакта.
Создадим файл с html-формой и назовём его form.php
Создание манифеста
Манифест виджета – это файл с описанием и настройками виджета в формате JSON. Рекомендуется название, описание и другую статичную информацию выносить в файлы локализации виджета (смотрите ниже). Внимание! code и secret_key должны соответствовать, загруженному в аккаунт виджету.
Создание файлов локализации
Файл локализации – это файл в формате JSON, содержащий перевод статичной информации, используемой при разработке виджета. Эти файлы редактируются по мере написания логики виджета, в зависимости от необходимости ввода той или иной новой информации.
Создадим два файла локализации для нашего примера: на английском и на русском языках соответственно.
Файл англоязычной локализации
Программирование виджета
Создадим пустой класс Widget, который наследует системный класс \Helpers\Widgets, а затем сделаем в нём точку входа, которую назовём add
Создадим внутренний метод get_data() (помеченный модификатором private), который будет получать данный из формы, и записывать их во внутреннее свойство $data, а затем поместим его вызов в точку входа.
Создадим внутренний метод get_custom_fields_info() для получения информации о нужных нам полях в amoCRM и сохраним его результат в переменной $custom_fields в точке входа.
Теперь нам необходимо узнать, существует ли контакт с указанным E-mail у пользователя. Для этого создадим внутренний метод is_contact_exists() и сделаем соответствующую проверку в точке входа.
Наконец, можем создать контакт в amoCRM. Для этого напишем внутренний метод add_new_contact ($custom_fields), принимающий в качестве параметра массив с информацией, которую мы собрали в методе get_custom_fields_info() и вызовем его в точке входа.
Теперь PHP-логика нашего виджета готова!
Отладка
В ходе разработки своего виджета для интеграции с amoCRM, Вы можете столкнуться с числовыми кодами состояний или ошибок, возвращаемых вместе с ответом нашим API. Для того чтобы понять, что именно означает тот или иной код вы можете воспользоваться нашим справочником ответов API или использовать метод \Helpers\Curl::get_error_code($code), который возвращает сообщение ошибки по её числовому коду.
Упаковка и загрузка
Если при работе вы указали значение константы AUTO_BUILD как true то в папке, где вы создавали виджет должна быть автоматически создана структура /widgets/code/ (если же этой папки нет, вам необходимо обратиться к контроллеру builder вручную) где code – код виджета. В ней содержится архив widget.zip, который необходимо загрузить на amoCRM в разделе /settings/dev/
Качаем PHP-библиотеку для разработки виджетов
Вы всегда можете скачать актуальную версию php-библиотеки по ссылке, расположенной ниже:
А пример, приведённый на этой странице, доступен здесь:
EVENTS
Events provide the ability to add additional structured or unstructured information to an entity element. Events can be system calls (calls, SMS messages, etc.) created by the user (notes, files). The events in the cards are displayed alongside the to-dos, because do not have a responsible one and are not attached to the date.
Often events are used by widgets to add additional information to a lead or contact, when it is not very convenient to use additional fields. Events are very convenient to use as a log, because they are always displayed in chronological order in the tape, and if your information is tied to a date (chronology), then it is desirable to use events.
Adding and updating events
The method allows you to add new or update existing events.
POST / api / v2 / notes
| Parameter | Type | Description |
|---|---|---|
| add | array | The list of events to add |
| update | array | Updates existing events. All the parameters that are described in add also work in the update |
| add/element_id require | int | id of the element, the event will be added to the card |
| add/element_type require | int | The type of the entity in which the event is added to the card. Available types, see here |
| add/text require | string | Event text |
| add/note_type require | int | The type of the event to add. Available types, see here |
| add/created_at | timestamp | Date and time the event was created |
| add/updated_at | timestamp | Date and time of event modification |
| add/responsible_user_id | int | iid of the user responsible for the event. If you restrict access rights, only this user will be allowed to make changes to this event in the entity card. |
| add/params | int | An array with the information to be sent for certain types of events. See here. |
| update/id require | int | id of the event to be modified |
| update/updated_at require | timestamp | Date and time of event change |
| Code | Description |
|---|---|
| 1 | Contact |
| 2 | Lead |
| 3 | Company |
| 4 | The task. For the task, only the TASK_RESULT event type is available |
| 12 | Customer |
| Code | Type | Description |
|---|---|---|
| 1 | LEAD_CREATED | Lead created |
| 2 | CONTACT_CREATED | Contact created |
| 3 | LEAD_STATUS_CHANGED | Lead status changed |
| 4 | COMMON | Normal note |
| 10 | CALL_IN | Incoming call |
| 11 | CALL_OUT | Outgoing call |
| 12 | COMPANY_CREATED | Company created |
| 13 | TASK_RESULT | Result by task |
| 25 | SYSTEM | System message |
| 102 | SMS_IN | Incoming SMS |
| 103 | SMS_OUT | Outgoing SMS |
Types of events for which the params array is required
| Type | Structure | Description |
|---|---|---|
| 10-11 | ‘params’ => [ ‘UNIQ’ =>’676sdfs7fsdf’, ‘LINK’ => ‘www.testweb.com/test_call.mp3’, ‘PHONE’ => ‘+14950000001’, ‘DURATION’ => 58, ‘SRC’ => ‘asterisk’ ] | Parameters for creating a call-type event. The params array is passed instead of the text parameter. |
| 25 | ‘params’ => [ ‘text’ => ‘The text of the system message’ ] | For the “system message” event type, the text is sent using the params array, instead of the text parameter. |
| 102-103 | ‘params’ => [ ‘text’ => ‘SMS message text’ ] | For the event type “sms message”, the text is sent using the params array, instead of the text parameter. |
| Parameter | Description |
|---|---|
| id | The unique identifier of the new entity |
| request_id | The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated |
| _links | Array containing information about the request |
| _links/self | An array containing information about the current request |
| _links/self/href | Relative URL of the current request |
| _links/self/method | The method of the current request |
| _embedded | An array containing information adjacent to the query |
| _embedded/items | An array containing information for each individual element |
Example of integration
Adding calls through an event
When specifying the appropriate types and parameters, the event can be written to the entity card as a call.
| Type | Description |
|---|---|
| 1 | Left a voice message |
| 2 | Call back later |
| 3 | Not available |
| 4 | The conversation took place |
| 5 | Wrong number |
| 6 | Did not get through |
| 7 | Number is busy |
Example of integration
List of events
Method for obtaining a list of notes with the possibility of filtering and pagination. Restriction on data returned on one page (offset) – 500 entries.
Amo crm api php
Инициализация клиента по oAuth
Хранение oauth токена возможно в нескольких вариантах
Используется по умолчанию (/vendor/ufee/amoapi/src/Cache/), можно задать свой путь
Создается поддиректория:
Настоятельно рекомендуется использовать cвой путь для кеширования, в противном случае данные будут УДАЛЕНЫ composer’ом при обновлении на новую версию.
Поддерживается библиотека phpredis
Формат ключа:
Реализуется класс, наследующий \Ufee\Amo\Base\Storage\Oauth\AbstractStorage
Кеширование oauth данных библиотекой не производится
Задать свой путь для кеширования oauth данных (устаревший метод)
Получение объекта для работы с конкретным аккаунтом
Получение ранее инициализированного объекта по id приложения
Получение URL авторизации в приложении amoCRM
Необходимо для извлечения кода авторизации
При необходимости можно задать oauth данные принудительно, вручную
Данные также будут кешированы автоматически в соответствии с выбранным хранилищем
Токен доступа обновляется автоматически, если срок действия refresh_token не истек
При необходимости можно обновить oauth данные по refresh_token принудительно, вручную
Новые oauth данные также будут кешированы автоматически
Вызов callback функции при автоматическом обновлении токена доступа
После первичного выполнения метода fetchAccessToken(), можно пользоваться клиентом в обычном режиме
Повторное выполнение метода fetchAccessToken() или setOauth() необходимо только в случаях, если:
Обмен API ключа на код авторизации oAuth
Инициализация клиента по API-hash
Получение объекта для работы с конкретным аккаунтом
Включение/выключение автоматической авторизации при ошибке 401
Сессия (cookie) кешируется в файлах
Включение логирования заросов (Logs/m-Y/domain.log)
Не более 1 запроса за заданное время, в секундах
Запрос /api/v2/account кешируется в файлах, время указывается в секундах
Свой путь для кеширования запросов
Пользовательская отладка запросов (обновлено с вводом oAuth)
Поиск по дополнительному полю
Работа с дополнительными полями
Работа с коллекциями
Перебор, поиск и фильтрация
Работа со сделками
Получение всех сделок
Получение по дате последнего изменения
Получение сделок с дополнительным условием
Связанные сущности по сделке
Создание сделки из контакта
Работа с контактами
Получение всех контактов
Получение контактов с дополнительным условием
Связанные сущности по контакту
Создание контакта из сделки
Работа с компаниями
Получение всех компаний
Получение компаний с дополнительным условием
Связанные сущности по компании
Создание компании из контакта или сделки
Получение всех задач
Получение задач с дополнительным условием
Создание задачи из контакта, сделки или компании
Получение родительского контакта, сделки или компании
Работа с примечаниями
Получение всех примечаний
Получение примечаний по ID и типу сущности
Получение примечаний с дополнительным условием
Создание примечания из контакта, сделки или компании
Закрепление/открепление примечаний (note type 4)
Получение содержимого файла (note type 5)
Получение родительского контакта, сделки или компании
Работа со списками
Получение всех списков (каталогов)
Получение списков с дополнительным условием
Связанные сущности по списку
Работа с элементами каталога (товарами)
Связанные сущности по товару
Работа с покупателями
Получение всех покупателей
Получение покупателей с дополнительным условием
Связанные сущности покупателя
Создание покупателя из контакта
Работа с покупками
Получение транзакций (покупок)
Обновление комментариев транзакций покупателя
Как передать данные из формы в amoCRM с помощью API
Всем привет сегодня я вам покажу готовые скрипты которые я использую для передачи значений из формы обратной связи в amoCRM через API данного сервиса. Мы рассмотрим скрипт для создания сделок с прязкой контактов.
Каждый тип запроса я разбил по функциям, а полное подключение выложил в отдельную функцию, в самом конце. На данный момент, на 2020 год, эта реализация отрабатывает без каких либо ошибок.
Для того чтобы подключить ваш проект к amoCRM нужно сделать следующие действия:
1) Создать аккаунт на amoCRM
2) После этого переходим в Настройки и создаем новую интеграцию. Во время создания интеграции вам нужно указать адрес вашего сайта, предоставить все доступы для данной интеграции после чего сохранить.
3) После создания интеграции, переходим во вкладку “Ключи и доступы” – эти данные нам понадобятся для авторизации нашей интеграции. Мы не будем их использовать при каждом запросе, но переодически они нам будут нужны.
Внимание. Код авторизации обновляется каждые 20 мин, а значит если вы его скопируете за пару минут до обновления, вы можете не успеть сделать запрос и у вас выведется ошибка. Если у вас появилась ошибка связанная с авторизацией, то просто попробуйте заново копировать данные.
Теперь вам нужно создать PHP файл и в нем мы будем создавать подключение к нашей CRM системе.
Авторизация интеграции
Первый запрос нам нужно сделать на авторизацию созданной интеграции. Для своей задачи я использовал “Упрощённую систему авторизации” – https://www.amocrm.ru/developers/content/oauth/step-by-step#easy_auth
Для начала нам нужно выполнить запрос на авторизацию, код написан ниже. Для запроса я буду использовать библиотеку CURL.
Следующим запросом мы уже можем создавать наши контакты и сделки используя для авторизации наш токен.
Входные параметры
Для начала нужно подготовить массив с параметрами с удобным представлением. Для своей задачи я сделал следующий массив. Здесь перечислены основные переменные для запроса, у вас возможно будут свои данные, в дальнейшем вам просто нужно будет переделать функцию под себя.
Ключ CONTACT перечисляет данные для создания контакта. На последним этапе я делаю проверку, что если массив CONTACT пустой, то пользователь не создается, это сделано для форм в которых не указывается имя пользователя.
Создание контакта
Типичная ошибка при создание контакта, это нарушение структуры массива для запроса, поэтому внимательно создавайте массив для запроса. Ранее созданный массив с данными полей, мы передаем в функцию amoAddContact, где создается специальный массив для запроса.
Скажу сразу что я не понял как передавать значения для стандартных полей amoCRM типа телефон, email и прочих, поэтому я создал свои кастомные поля и уже в них передаю необходимые данные.
Каждое поле в запросе оборачивается в отдельный массив где id – это идентификатор поля, который вы можете получить следующим образом.
Функция amoAddContact возвращает id созданного контакта, которого мы будем привязывать к новой сделки.
Добавляем сделку
Сделка добавляется аналогично, в функцию передается токен и массив с параметрами + передается третий параметр contactId в котором указывается id контакта для привязки.
Сложность работы с amoCRM в том что у них access_token действует только сутки, по истечению времени он становится не рабочим и для того чтобы получить новый токен access_token вам нужно сделать запрос, передав refresh_token и вы получите новый access_token и refresh_token.
Нужно эти данные где то записать, чтобы можно было их использовать вновь на следующий день.
Для этого я сделал специальную функцию которая будет проверять актуальность токена и делать новый запрос если это необходимо.
Значения токенов будут сохраняться в файле в JSON формате.
Полный запрос на создание сделки
На последнем этапе я объединил все функции в одну для удобного использования. Теперь вам нужно будет только создать одну функцию которая, в которую передать массив с параметрами значений из формы.
Вспомогательные функции
Теперь давайте рассмотрим дополнительные функции, которые я выписал для себя, но думаю они вам тоже могут пригодиться.