Передача данных из AimyLogic для создания записи смарт-процесса в Битрикс (REST API)

Опубликовано 31.03.2023 автором Andrey Fedorov

В предыдущей статье я подробно рассмотрел создание лида в 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:

  1. Выполняется JSON для проверки есть ли клиент с заданным номером телефона.
  2. В блоке «Условие» производится проверка, если $contact_id == null, тогда выполняется блок «HTTP запрос» для создания нового клиента. В RESPONSE $client_id = $httpResponse.result.
  3. Если $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, т.е. «Другое».

Spread the love
Запись опубликована в рубрике IT рецепты. Добавьте в закладки постоянную ссылку.

Обсуждение закрыто.