В предыдущей статье я подробно рассмотрел создание лида в Bitrix с передачей необходимых параметров из AimyLogic. В этой статье рассмотрим как создать новый элемент (запись) для ранее созданного смарт-процесса. Создание смарт-процесса подробно рассмотрено в документации Битрикс: https://helpdesk.bitrix24.ru/open/13315798/ Останавливаться на этом не буду.
Я создал смарт-процесс с названием «Сервисная заявка». В неё из AimyLogic должны попадать заявки на сервисную поддержку для отработки инженерами сервисной службы.
Создание записи простого смарт-процесса через REST API
Создадим запись смарт-процесса в Битриксе через REST API. Запись смарт-процесса создается при вызове https://dev.1c-bitrix.ru/rest_help/crm/dynamic/methodscrmitem/crm_item_add.php
Ключевой параметр в аргументах crm.item.add — entityTypeId, т.е. идентификатор смарт-процесса. Чтобы найти этот параметр для созданного смарт-процесса переходим в CRM -> Ещё -> Настройки -> Список смарт-процессов:

В списке смарт-процессов первая колонка — идентификатор типа смарт-процесса. Это и есть искомый entityTypeId.

Сделаем простой тестовый запрос для отправки через Postman:
{ "entityTypeId": "158", "fields": { "TITLE": "ИП Титов" } }

При отправке запроса не забываем включать Headers и добавлять строчку:
Content-Type: application/json
иначе параметры из JSON не «лягут» в Битрикс.
После выполнения запроса в результатах получим следующий JSON:
{ "result": { "item": { "id": 2, "xmlId": null, "title": "ИП Титов", "createdBy": 177, "updatedBy": 177, "movedBy": 177, "createdTime": "2023-03-31T11:16:32+03:00", "updatedTime": "2023-03-31T11:16:32+03:00", "movedTime": "2023-03-31T11:16:32+03:00", "categoryId": 5, "opened": "N", "stageId": "DT158_5:NEW", "previousStageId": "", "begindate": "2023-03-31T03:00:00+03:00", "closedate": "2023-04-07T03:00:00+03:00", "companyId": null, "contactId": null, "opportunity": 0, "isManualOpportunity": "N", "taxValue": 0, "currencyId": "RUB", "opportunityAccount": 0, "taxValueAccount": 0, "accountCurrencyId": "RUB", "mycompanyId": null, "sourceId": "CALL", "sourceDescription": null, "webformId": null, "assignedById": 177, "observers": [], "contactIds": [], "utmSource": null, "utmMedium": null, "utmCampaign": null, "utmContent": null, "utmTerm": null, "entityTypeId": 158 } } }
В результирующем JSON фигурируют все поля созданного смарт-процесса.
Пользовательские поля в смарт-процессах
Добавим в созданный смарт-процесс несколько новых полей:

Для обработки сервисными инженерами голосовой бот должен получить от клиента следующую информацию:
- модель оборудования по которому возник вопрос,
- регион откуда звонит клиент (от этого зависит, например, где находятся ближайшие сервисцентры).
- описание проблемы (вопрос),
- если клиент считает, что оборудование на гарантии — дату производства с стикера на котле,
- имя клиента,
- номера телефона для связи.
Для примера создадим поле «Регион»:

Повторюсь, что после создания элемента смарт-процесса возвращается JSON со списком всех полей смарт-процесса с их значениями. Например, после добавления пары полей в JSON появляются записи:
... "ufCrm3_1680254883": "", "ufCrm3_1680255422": "", ...
Обратщаю внимание на тот момент, что в интерфейсе Битрикса название поля «UF_CRM_3_1680254883«, а в JSON, который возвращается от Битрикса это поле называется «ufCrm3_1680254883«. Соответственно, для отправки через REST API нужно использовать имя, которое возвращается в JSON при добавлении элемента смарт-процесса. Не знаю, зачем сделали такое различие в именах, вносящее путаницу.
{ "entityTypeId": "158", "fields": { "SOURCE_ID": "14", "contactId": "10060", "ufCrm3_1680255422": "EvanExpert", "ufCrm3_1680254883": "Москва", "ufCrm3_1680261235": "Проблема пользователя", "ufCrm3_1680261458": "16.10.2022" } }
При выполнении запроса возвращается JSON следующего вида:
{"item":{"id":151,"xmlId":null,"title":"Сервисная заявка #151","createdBy":177,"updatedBy":177,"movedBy":177,"createdTime":"2023-05-26T16:08:58+03:00","updatedTime":"2023-05-26T16:08:58+03:00","movedTime":"2023-05-26T16:08:58+03:00","categoryId":5,"opened":"N","stageId":"DT1585:NEW","previousStageId":"","begindate":"2023-05-26T03:00:00+03:00","closedate":"2023-06-02T03:00:00+03:00","companyId":null,"contactId":11599,"opportunity":0,"isManualOpportunity":"N","taxValue":0,"currencyId":"RUB","opportunityAccount":0,"taxValueAccount":0,"accountCurrencyId":"RUB","mycompanyId":null,"sourceId":"14","sourceDescription":null,"webformId":null,"ufCrm31680254883":"Великий Новгород","ufCrm31680255422":"ExpertPlus","ufCrm31680261235":"Тест","ufCrm31680261458":"01.01.1900","ufCrm31682360216":"","ufCrm3_1682682092":null,"assignedById":177,"observers":[],"contactIds": 11599,"utmSource":null,"utmMedium":null,"utmCampaign":null,"utmContent":null,"utmTerm":null,"entityTypeId":158}}
Например, чтобы получить номер заявки надо при возврате:
$ticket = $httpResponse.result; $ticket_id = $ticket.item.id;
В переменной $ticket_id содержится номер только что созданной сервисной заявки.
Добавление контакта через REST API
Для добавления контакта используется метод Битрикса crm.contact.add. JSON для REST API выглядит так:
{ "fields": { "NAME": "Андрей", "SECOND_NAME": "Алексеевич", "LAST_NAME": "Федоров", "TYPE_ID": "CLIENT", "SOURCE_ID": "SELF", "OPENED": "Y", "PHONE": [{"VALUE": "+79XXXXXXXXX", "VALUE_TYPE": "MOBILE"}, {"VALUE": "+79YYYYYYYYY", "VALUE_TYPE": "HOME"}] } }
В Postman этот запрос:

После отправки запроса получаем результат, где в поле result содержится ID созданной записи:
{ "result": 12062 }
При повторном звонке клиента нужно по номеру телефона найти контакт в Битриксе. Фильтрация описанная здесь не отрабатывает на номерах телефонов. Точное значение ищется, а вот маски или номера, когда в одном случае номер начинается с +7, а в другом с 8 — не находятся.
Единственный рабочий метод, который нормально находит идентификаторы клиента по номеру телефона, оказался вот этот: https://dev.1c-bitrix.ru/rest_help/crm/auxiliary/duplicates/crm_duplicate_findbycomm.php
JSON запрос выглядит следующим образом:
{ "entity_type": "CONTACT", "type": "PHONE", "values": [ "+7960XXXXXXX", "8906XXXXXXX"] }
Поиск этим методом проходит по полному номеру телефона, т.е. номер должен начинатся для России с +7 или 7 или 8 и дальше 10 цифр номера телефона. Маски задавать нельзя.
Однако, этот поиск находит все варианты записи телефона, даже если при сохранении номера начинались с +7 или 8 или были указаны разделители в виде «-«. Результат возвращается в виде массива с ID из контактов:
{ "result": { "CONTACT": [ 11599, 11600, 12062, 12063, 12064 ] } }
Возвращаются все контакты у которых встречается этот номер телефона. В AimyLogic JSON на получение контакта такой-же, как вышеприведенный. Результат $httpResponse.result сохраняется в переменную $contacts. На ветвление с успешной отработкой HTTP запроса нужно прописать короткий JavaScript:
if ($contacts.hasOwnProperty("CONTACT")) { if ($contacts.CONTACT.length > 0) { $contact_id = $contacts.CONTACT[0] } } else { $contact_id = null; }
Производится проверка, что в переменной $contacts присутствует свойство «CONTACT», после чего проверяется, что размер массива содержит хотя-бы один элемент и этот единственный ID контакта перемещается в переменную $contact_id. Найденное значение используется при создании нового контакта.
В Aimylogic:
- Выполняется JSON для проверки есть ли клиент с заданным номером телефона.
- В блоке «Условие» производится проверка, если $contact_id == null, тогда выполняется блок «HTTP запрос» для создания нового клиента. В RESPONSE $client_id = $httpResponse.result.
- Если $contact_id !== null, то клиент уже есть в Битриксе и в запросе на создание элемента смарт-процесса используется полученный при выполнении запроса $contact_id.
{ "entityTypeId": "158", "fields": { "SOURCE_ID": "14", "contactId": "$contact_id", "ufCrm3_1680255422": "$equipment", "ufCrm3_1680254883": "$client_city", "ufCrm3_1680261235": "$question", "ufCrm3_1680261458": "$productiondate" } }
Добавление в смарт-процесса Битрикс поля с типом «Список»
Чтобы добавить в созданный смарт-процесс Bitrix поля с типом «Список» нужно найти ID элементов из списка. В интерфейсе Bitrix это сделать не получилось, поэтому нужно вызвать метод crm.item.fields.json, передав в параметре id смарт-процесса.
В POST запросе в Postman URL для теста выглядит как-то так: https://xxxxx.ru/rest/yyy/zzzzzzzzz/crm.item.fields.json
В headers:
Content-Type: application/json
Body:
{ "entityTypeId": "158" }
Ну и в result получаем JSON со списком всех полей смарт-процесса:
"ufCrm3_1697115862": { "type": "enumeration", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": true, "items": [ { "ID": "59", "VALUE": "Другое." }, { "ID": "55", "VALUE": "Котел не греет. Сломался. " } ], "title": "Важность", "listLabel": "", "formLabel": "Важность", "filterLabel": "", "settings": { "DISPLAY": "LIST", "LIST_HEIGHT": 1, "CAPTION_NO_VALUE": "", "SHOW_NO_VALUE": "Y" }, "upperName": "UF_CRM_3_1697115862" },
Добавляем это поле в JSON:
{ "entityTypeId": "158", "fields": { "SOURCE_ID": "14", "contactId": "$contact_id", "ufCrm3_1680255422": "$equipment", "ufCrm3_1680254883": "$client_city", "ufCrm3_1680261235": "$question", "ufCrm3_1680261458": "$productiondate", "ufCrm3_1697115862": "59" } }
Смарт процесс успешно создается и значение поля типа «Список» устанвливается с id = 59, т.е. «Другое».