Как передать данные из формы в 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 создание сделки
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 могут остаться без ответа и действия, в случае, если правки потенциально жизнеспособны, но в данный момент не являются ключевыми для проекта.
Leads
Adding and updating a lead
The method allows you to add leads one by one or in bulk, as well as update data on existing leads.
| Parameter | Type | Description |
|---|---|---|
| add | array | List of added deals |
| update | array | Updating existing leads All the parameters that are described in add also work in the update |
| add/name require | string | Name of the lead |
| add/created_at | timestamp | Date of the current lead creation |
| add/updated_at | timestamp | Date of the current lead change |
| add/status_id | int | Status of the lead (id of the sales phase, see Pipelines and stages of sales) To transfer the lead to another pipeline, you need to set its status from the desired pipeline |
| add/pipeline_id | int | ID of the pipeline. It is indicated if id 142 or 143 statuses are selected, because These statuses are not unique and are mandatory for all digital pipelines. |
| add/responsible_user_id | int | ID of the responsible user |
| add/sale | int | Deal budget |
| add/tags | array/string | If you want to specify new tags, list them inside the string variable, separated by commas. If you need to attach existing tags, pass an array of numeric id values of existing tags. |
| add/contacts_id | int/array | The unique identifier for the contact to contact the lead. You can pass multiple id, listing them in an array separated by commas. |
| add/company_id | int | The unique identifier of the company to contact the lead |
| add/custom_fields | array | Inside this array is the contents of each filled additional field |
| add/custom_fields//id | int | The unique identifier of the additional field to be populated |
| add/custom_fields//values | array | Array of values |
| add/custom_fields//values//value | string | The value of the additional field |
| add/custom_fields//values//subtype | string | The type of the element to change the additional field of the address type. Caution, all types that were not transferred will be erased |
| update/id require | int | id of the lead to be changed |
| update/updated_at required | timestamp | Time |
| update/unlink | array | An array containing information to detach a lead from other entity elements. |
| update/unlink/contacts_id | array | Array id of unlinked contacts |
| update/unlink/company_id | int | id of the company to be uninstalled |
Here is an example of a request to add a new lead.
Here is an example of a request for changes in the data of an existing lead.
Description of response parameters
| 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 | An array containing information about the query |
| _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 |
Response Headers contains the following headers:
Example of integration
To add a lead, you need to describe an array containing information about it. Our API also supports the simultaneous addition of several leads at once. To do this, we place several arrays in the query array, each describes the necessary data to create the corresponding lead.
List of leads
Method for obtaining a list of leads with the possibility of filtering and pagination. Restriction on data returned on one page (offset) – 500 leads.
| Parameter | Description |
|---|---|
| limit_rows | Number of selectable rows (system limit 500) |
| limit_offset | Shift the selection (from which row to choose). Works only if limit_rows is also specified |
| id | Select the element with the given ID (If this parameter is specified, all the others are ignored). Can be sent as an array consisting of several IDs |
| query | Search query (Searches for the filled fields of the entity) |
| responsible_user_id | Additional search filter, by responsible user (Can be transferred as an array) |
| status | Filter by lead status ID (See here for a list of available IDs) (Can be transferred as an array) |
You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the D format, d M Y H: i: s. When this header is transmitted, the leads changed later than this date will be returned. The title should be sent in the UTC time zone.
Description of response parameters
| Parameter | Type | Description |
|---|---|---|
| id | int | Unique trade identifier |
| name | string | Name of the lead |
| responsible_user_id | int | id of the responsible user |
| created_by | int | id of the user who created the lead |
| created_at | timestamp | The time and date the lead was created |
| updated_at | timestamp | Date and time of the lead change |
| account_id | int | id of the account on which the lead was created |
| is_deleted | bool | Deal deleted or not. Deleted leads can be in “deleted” |
| main_contact | array | An array containing information about the main contact of the lead |
| main_contact/id | int | id of the main contact of the lead |
| group_id | int | id of the group in which the user is responsible for the lead |
| company | array | An array containing information about a company that is attached to a given lead |
| company/id | int | id of the company that is attached to this lead |
| company/name | string | The name of the company that is attached to the lead |
| closed_at | timestamp | The time and date when this lead was completed |
| closest_task_at | timestamp | The time of the nearest task for this lead |
| tags | array | An array containing information on tags attached to a given lead |
| tags/id | int | id of the tag attached to this trade |
| tags/name | string | The name of the tag attached to this lead |
| custom_fields | array | An array containing information on the additional fields specified for this lead |
| custom_fields//id | int | id of the custom field |
| custom_fields//name | string | name of the custom field |
| custom_fields//values | array | An array containing information on the custom fields specified for this lead |
| custom_fields//values//value | string | The value of the custom field |
| custom_fields//values//enum | string | Early identifier of the preset option for the list or multisession |
| custom_fields//values//subtype | string | The identifier of the values of the additional field “address” |
| custom_fields//is_system | bool | Is the extra field systemic |
| contacts | array | An array containing information on contacts attached to a given lead |
| contacts/id | int | id of the contact attached to the lead |
| status_id | int | id of the digital pipeline segment on which the lead is located |
| sale | int | Budget of the lead |
| pipeline | array | An array containing information on the digital pipeline in which the lead is located |
| pipeline/id | int | id of the digital pipeline in which the lead is located |
| _links | array | Array containing information about the request |
| _links/self | array | An array containing information about the current request |
| _links/self/href | string | Relative URL of the current request |
| _links/self/method | string | Method of the current request |
| _embedded | array | An array containing information adjacent to the query |
| _embedded/items | array | An array containing information for each individual element |
Response Headers contains the following headers: