amocrm api php примеры

Как передать данные из формы в 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 формате.

Полный запрос на создание сделки

На последнем этапе я объединил все функции в одну для удобного использования. Теперь вам нужно будет только создать одну функцию которая, в которую передать массив с параметрами значений из формы.

Вспомогательные функции

Теперь давайте рассмотрим дополнительные функции, которые я выписал для себя, но думаю они вам тоже могут пригодиться.

Источник

Amocrm api php примеры

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. Методы сгруппированы и объекты-сервисы. Получить объект сервиса можно вызвав необходимый метод у библиотеки, например:

В данный момент доступны следующие сервисы:

Для большинства сервисов есть базовый набор методов:

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

У выброшенных Exception есть следующие методы:

В данный момент библиотека поддерживает фильтры для следующих сервисов:

Работа с дополнительными полями сущностей

Дополнительные поля доступны у сущностей следующих сервисов:

У моделей, наследующих BaseCustomFieldValuesModel доступны следующие методы:

Схема отношений объектов:

CustomFieldsValuesCollection 1 n BaseCustomFieldValuesModel BaseCustomFieldValuesModel::getValues() 1 1 BaseCustomFieldValueCollection BaseCustomFieldValueCollection 1 n BaseCustomFieldValueModel

Для разных типов полей мы уже подготовили разные модели и коллекции:

Пример кода, как создать коллекцию значения полей сущности:

Передав этот объект, вы зануляете значение поля.

Работа с тегами сущностей

Для работы с тегами конкретной сущности, нужно взаимодействовать с конкретной моделью сущности. С помощью методов getTags и setTags вы можете получить коллекцию тегов сущности или установить её.

Для изменения тегов вам необходимо передавать всю коллекцию тегов, иначе теги могут быть потеряны.

Пример добавления/изменения тегов у сущности:

Пример удаления тегов у сущности:

Также доступны константы в следующих классах/интерфейсах:

Работа в случае смены субдомена аккаунта

Одноразовые токены интеграций, расшифровка

Также вы можете распарсить и модель одноразового токена для Salesbot/Marketingbot. Для этого необходимо сделать вызов метода parseBotDisposableToken:

В рамках данного репозитория имеется папка examples с различными примерами.

После авторизации вы можете проверить работу примеров, обращаясь к ним из браузера. Стоит отметить, что для корректной работы примеров необходимо проверить ID сущностей в них.

Если вы столкнулись с проблемой при работе с библиотекой, вы можете составить Issue, который будет рассмотрен при первой возможности.

При составлении, детально опишите проблему, приложите примеры кода, а также ответы на запросы из getLastRequestInfo.

Не забывайте удалять из примеров значимые данные, которые не должны быть достоянием общественности.

Также могут быть рассмотрены пожелания по улучшению библиотеки.

Вы можете предложить свои исправления/изменения исходного кода библиотеки, посредством создания Issue с описанием, а также Pull request с упоминанием Issue в комментарии к нему. Они будут рассмотрены и будут приняты или отклонены. Некоторые Pull Request могут остаться без ответа и действия, в случае, если правки потенциально жизнеспособны, но в данный момент не являются ключевыми для проекта.

Источник

Amocrm 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-библиотеки по ссылке, расположенной ниже:

А пример, приведённый на этой странице, доступен здесь:

Источник