php скрипт который работает с api системы amocrm
Php скрипт который работает с api системы amocrm
Простая обертка для работы с API AmoCRM.
На данный момент для запросов доступны следующие объекты:
Добавьте в блок «require» в composer.json вашего проекта
Или введите в консоли
Подготовка к работе и настройка
Создайте папку «config» в корне пакета, куда положите два файла:
Файл с конфигом используется для хранения номеров кастомных полей из AmoCRM, которые вы будете использовать в своей работе, и должен возвращать ассоциативный массив, например:
Номера полей вашего аккаунта можно получить так:
На страницу будет выведена вся информация об аккаунте.
Выбираете номера нужных полей (номера пользователей, номера кастомных полей сделок и т.д.) и сохраняете в конфиг с понятными вам названиями.
Файл с ключом должен содержать в себе API-ключ выбранного пользователя.
Вы также можете передать дополнительный параметр «IF-MODIFIED-SINCE», в котором указывается дата в формате D, d M Y H:i:s. При передаче этого параметра будут возвращены сущности, изменённые позже этой даты.
Создание новых объектов
Пример рабочего кода, который покрывает все доступные возможности библиотеки
Есть возможность создавать одновременно несколько объектов одного типа и отправлять их в amoCRM одним запросом
В случае ошибки запроса к API, AmoCRM возвращает только номер ошибки, без текстовых пояснений.
Чтобы включить текстовые пояснения для ошибок, передайте в конструктор хендлера «true» третьим параметром:
Теперь вместе с номером ошибки вы будете видеть и что же этот номер означает, и упростите дебаггинг.
Включение этого режима создает дополнительный запрос к диску на чтение файла, где сохранены описания ошибок, поэтому не забудьте отключить дебаггинг в продакшене.
Как настроить аккаунт на работу с вебхуками смотрите здесь.
Чтобы успешно обрабатывать запрос от AmoCRM на ваш сайт, вам нужно создать слушателя событий в файле, на который AmoCRM шлет свои запросы, и определить функции, которые будут вызываться при определенном событии.
Список доступных событий
Обратите внимание, что при смене статуса сделки или при смене ответственного сделки, AmoCRM одновременно посылает информацию и об общем изменении сделки, то есть код для leads-status и leads-responsible всегда будет выполняться вместе с leads-update.
Php скрипт который работает с api системы amocrm
Внимание! 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-библиотеки по ссылке, расположенной ниже:
А пример, приведённый на этой странице, доступен здесь:
Php скрипт который работает с api системы amocrm
Клиент для работы с 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
Интеграция с фреймворками
Php скрипт который работает с api системы amocrm
amoCRM API Library
В данном пакете представлен API клиент с поддержкой основных сущностей и авторизацией по протоколу OAuth 2.0 в amoCRM. Для работы библиотеки требуется PHP версии не ниже 7.1.
Установить библиотеку можно с помощью composer:
Начало работы и авторизация
Для начала использования вам необходимо создать объект бибилиотеки:
Затем необходимо создать объект ( \League\OAuth2\Client\Token\AccessToken ) Access токена из вашего хранилища токенов и установить его в API клиент.
Также необходимо установить домен аккаунта amoCRM в виде СУБДОМЕН.amocrm.(ru/com).
Вы можете установить функцию-callback на событие обновления Access токена, если хотите дополнительно обрабатывать новый токен (например сохранять его в хранилище токенов):
Отправить пользователя на страницу авторизации можно 2мя способами:
Для получения Access Token можно использовать следующий код в обработчике, который будет находится по адресу, указаному в redirect_uri
Пример авторизации можно посмотреть в файле examples/get_token.php
Подход к работе с библиотекой
В библиотеке используется сервисный подход. Для каждой сущности имеется сервис. Для каждого метода имеется свой объект коллекции и модели. Работа с данными происходит через коллекции и методы библиотеки.
Также для работы с коллекциями имеют следующие методы:
При работе с библиотекой необходимо не забывать о лимитах API amoCRM. Для оптимальной работы с данными лучше всего создавать/изменять за раз не более 50 сущностей в методах, где есть пакетная обработка.
Нужно не забывать про обработку ошибок, а также не забывать о безопасности хранилища токенов. Утечка токена грозит потерей досутпа к аккаунту.
Поддерживаемые методы и сервисы
Библиотека поддерживает большое количество методов API. Методы сгруппированы и объекты-сервисы. Получить объект сервиса можно вызвав необходимый метод у библиотеки, например:
В данный момент доступны следующие сервисы:
| Сервис | Цель сервиса |
|---|---|
| notes | Примечание сущности |
| tags | Теги сущностей |
| tasks | Задачи |
| leads | Сделки |
| contacts | Контакты |
| companies | Компании |
| catalogs | Каталоги |
| catalogElements | Элементы каталогов |
| customFields | Пользовательские поля |
| customFieldGroups | Группы пользовательских полей |
| account | Информация об аккаунте |
| roles | Роли пользователей |
| users | Роли юзеров |
| customersSegments | Сегменты покупателей |
| events | Список событий |
| webhooks | Вебхуки |
| unsorted | Неразобранное |
| pipelines | Воронки сделок |
| statuses | Статусы сделок |
| widgets | Виджеты |
| lossReason | Причины отказа |
| transactions | Покупки покупателей |
| customers | Покупатели |
| customersStatuses | Сегменты покупателя |
| customersBonusPoints | Бонусные баллы покупателя |
| calls | Звонки |
| products | Товары |
| links | Массовая привязка сущностей |
| shortLinks | Короткие ссылки |
| talks | Беседы |
| entitySubscriptions | Подписчики сущности |
| getOAuthClient | oAuth сервис |
| getRequest | Голый запросы |
Для большинства сервисов есть базовый набор методов:
get Получить несколько сущностей:
addOne Создать одну сущность:
add Создать сущности пакетно:
updateOne Обновить одну сущность:
update Обновить сущности пакетно:
syncOne Синхронизировать одну модель с сервером:
Не все методы доступны во всех сервисах. В случае их вызова будет выброшены Exception.
Некоторые сервисы имеют специфичные методы, ниже рассмотрим сервисы, которые имеют специфичные методы.
Методы доступные в сервисе leads :
Подробней про использование метода комплексного создания смотрите в примере
Методы доступные в сервисе getOAuthClient :
getAuthorizeUrl получение ссылки на авторизация
getAccessTokenByCode получение аксес токена по коду авторизации
getAccessTokenByRefreshToken получение аксес токена по рефреш токену
setBaseDomain установка базового домена, куда будут отправляться запросы необходимые для работы с токенами
setAccessTokenRefreshCallback установка callback, который будет вызван при обновлении аксес токена
getOAuthButton установка callback, который будет вызван при обновлении аксес токена
exchangeApiKey метод для обмена API ключа на код авторизации
link Привязать сущность
getLinks Получить связи сущности
unlink Отвязать сущность
Методы доступные в сервисе customers :
Методы доступные в сервисе customersBonusPoints :
earnPoints Начисляет бонусные баллы покупателю
redeemPoints Списывает бонусные баллы покупателя
Методы доступные в сервисе account
Методы доступные в сервисе unsorted
addOne Создать одну сущность:
add Создать сущности пакетно:
Методы доступные в сервисе webhooks
Методы доступные в сервисе widgets
Методы доступные в сервисе products
Методы, доступные в сервисе talks
| Тип | Условия |
|---|---|
| AmoCRM\Exceptions\AmoCRMApiConnectExceptionException | Подключение к серверу не было выполнено |
| AmoCRM\Exceptions\AmoCRMApiErrorResponseException | Сервер вернул ошибку на выполняемый запрос |
| AmoCRM\Exceptions\AmoCRMApiHttpClientException | Произошла ошибка http клиента |
| AmoCRM\Exceptions\AmoCRMApiNoContentException | Сервер вернул код 204 без результата, ничего страшного не произошло, просто нет данных на ваш запрос |
| AmoCRM\Exceptions\AmoCRMApiTooManyRedirectsException | Слишком много редиректов (в нормальном режиме не выкидывается) |
| AmoCRM\Exceptions\AmoCRMoAuthApiException | Ошибка в oAuth клиенте |
| AmoCRM\Exceptions\BadTypeException | Передан не верный тип данных |
| AmoCRM\Exceptions\InvalidArgumentException | Передан не верный аргумент |
| AmoCRM\Exceptions\NotAvailableForActionException | Метод не доступен для вызова |
| AmoCRM\Exceptions\AmoCRMApiPageNotAvailableException | Выбрасывается в случае запроса следующей или предыдущей страницы коллекции, когда страница отстутвует |
| AmoCRM\Exceptions\AmoCRMMissedTokenException | Не установлен Access Token для выполнения запроса |
У выброшенных Exception есть следующие методы:
В данный момент библиотека поддерживает фильтры для следующих сервисов:
Работа с дополнительными полями сущностей
Дополнительные поля доступны у сущностей следующих сервисов:
У моделей, наследующих BaseCustomFieldValuesModel доступны следующие методы:
Схема отношений объектов:
CustomFieldsValuesCollection 1 n BaseCustomFieldValuesModel BaseCustomFieldValuesModel::getValues() 1 1 BaseCustomFieldValueCollection BaseCustomFieldValueCollection 1 n BaseCustomFieldValueModel
Для разных типов полей мы уже подготовили разные модели и коллекции:
| Тип поля | Модель значения | Коллекция моделей значений | Модель доп поля | Контакт | Сделка | Компания | Покупатель | Каталог | Сегмент |
|---|---|---|---|---|---|---|---|---|---|
| Текст | TextCustomFieldValueModel | TextCustomFieldValueCollection | TextCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Число | NumericCustomFieldValueModel | NumericCustomFieldValueCollection | NumericCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Флаг | CheckboxCustomFieldValueModel | CheckboxCustomFieldValueCollection | CheckboxCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Список | SelectCustomFieldValueModel | SelectCustomFieldValueCollection | SelectCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Мультисписок | MultiselectCustomFieldValueModel | MultiselectCustomFieldValueCollection | MultiSelectCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Мультитекст | MultitextCustomFieldValueModel | MultitextCustomFieldValueCollection | MultitextCustomFieldValuesModel | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Дата | DateCustomFieldValueModel | DateCustomFieldValueCollection | DateCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Ссылка | UrlCustomFieldValueModel | UrlCustomFieldValueCollection | UrlCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Дата и время | DateTimeCustomFieldValueModel | DateTimeCustomFieldValueCollection | DateTimeCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Текстовая область | TextareaCustomFieldValueModel | TextareaCustomFieldValueCollection | TextareaCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Переключатель | RadiobuttonCustomFieldValueModel | RadiobuttonCustomFieldValueCollection | RadiobuttonCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Короткий адрес | StreetAddressCustomFieldValueModel | StreetAddressCustomFieldValueCollection | StreetAddressCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Адрес | SmartAddressCustomFieldValueModel | SmartAddressCustomFieldValueCollection | SmartAddressCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| День рождения | BirthdayCustomFieldValueModel | BirthdayCustomFieldValueCollection | BirthdayCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Юр. лицо | LegalEntityCustomFieldValueModel | LegalEntityCustomFieldValueCollection | LegalEntityCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Цена | PriceCustomFieldValueModel | PriceCustomFieldValueCollection | PriceCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Категория | CategoryCustomFieldValueModel | CategoryCustomFieldValueCollection | CategoryCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Предметы | ItemsCustomFieldValueModel | ItemsCustomFieldValueCollection | ItemsCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Метка | TrackingDataCustomFieldValueModel | TrackingDataCustomFieldValueCollection | TrackingDataCustomFieldValuesModel | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Связанная сущность | LinkedEntityCustomFieldValueModel | LinkedEntityCustomFieldValueCollection | LinkedEntityCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
Пример кода, как создать коллекцию значения полей сущности:
Передав этот объект, вы зануляете значение поля.
Работа с тегами сущностей
Для работы с тегами конкретной сущности, нужно взаимодействовать с конкретной моделью сущности. С помощью методов getTags и setTags вы можете получить коллекцию тегов сущности или установить её.
Для изменения тегов вам необходимо передавать всю коллекцию тегов, иначе теги могут быть потеряны.
Пример добавления/изменения тегов у сущности:
Пример удаления тегов у сущности:
Также доступны константы в следующих классах/интерфейсах:
Работа в случае смены субдомена аккаунта
Одноразовые токены интеграций, расшифровка
Также вы можете распарсить и модель одноразового токена для Salesbot/Marketingbot. Для этого необходимо сделать вызов метода parseBotDisposableToken:
В рамках данного репозитория имеется папка examples с различными примерами.
После авторизации вы можете проверить работу примеров, обращаясь к ним из браузера. Стоит отметить, что для корректной работы примеров необходимо проверить ID сущностей в них.
Если вы столкнулись с проблемой при работе с библиотекой, вы можете составить Issue, который будет рассмотрен при первой возможности.
При составлении, детально опишите проблему, приложите примеры кода, а также ответы на запросы из getLastRequestInfo.
Не забывайте удалять из примеров значимые данные, которые не должны быть достоянием общественности.
Также могут быть рассмотрены пожелания по улучшению библиотеки.
Вы можете предложить свои исправления/изменения исходного кода библиотеки, посредством создания Issue с описанием, а также Pull request с упоминанием Issue в комментарии к нему. Они будут рассмотрены и будут приняты или отклонены. Некоторые Pull Request могут остаться без ответа и действия, в случае, если правки потенциально жизнеспособны, но в данный момент не являются ключевыми для проекта.