Внешние вызовы

Шаг Внешний вызов отправляет из workflow запрос в вашу систему: создать аккаунт в CRM, передать заказ, узнать баланс клиента. Ответ можно сохранить в переменную или в карточку клиента либо показать сотруднику.

Что получает ваша система и как ей отвечать, описано для программистов в статье Ваш API.

Создать подключение

Подключение хранит базовый адрес системы и ключ доступа. В шаге указывается только путь, поэтому ключ не попадает в настройки workflow и в журнал.

1. Откройте Настройки, раздел Подключения к API.
2. Нажмите Подключение.
3. Заполните поле Название, например Ваша CRM.
4. Заполните Базовый адрес, например https://crm.example.com/api/v1. Адрес начинается с http:// или https://.
5. Выберите тип в поле Авторизация и заполните ключ:
   • Без авторизации: ключ не нужен;
   • Bearer-токен: поле Токен;
   • Логин и пароль (Basic): поля Логин и Пароль;
   • Ключ в заголовке: поля Имя заголовка и Значение.
6. Нажмите Сохранить.

Сохранённый ключ больше не показывается. Чтобы при изменении подключения не менять ключ, оставьте его поле пустым.

Чтобы удалить подключение, сначала уберите его из всех workflow. Список этих workflow Polygram покажет при попытке удаления.

Настроить запрос

Пример: отправить в CRM данные из формы Данные для CRM.

1. На панели Добавить узел: нажмите Внешний вызов, соедините шаг с предыдущим и нажмите на него.
2. В разделе Куда в поле Подключение выберите Ваша CRM. Ссылка Настроить открывает список подключений.
3. Выберите метод POST и впишите путь /accounts. Под полем появится итоговый адрес.
4. В разделе Тело запроса оставьте вид Поля.
5. Нажмите Добавить поля формы (N). Появятся поля с именами из формы и значениями $vars.<ключ>. Кнопка есть, если выше по workflow стоит шаг Запросить данные.
6. Чтобы добавить поле вручную, нажмите Добавить поле, впишите имя, выберите тип и впишите значение или нажмите Вставить переменную.
7. Раскройте Пример запроса и проверьте тело.

Без подключения выберите вариант Без подключения — полный адрес и впишите адрес целиком с http:// или https://. Он подходит для систем без ключа или с ключом в заголовке шага.

В пути можно использовать переменные: /clients/$contact.custom.crm_id. Путь должен оставаться внутри базового адреса.

Сохранить ответ

1. В разделе Сохранить из ответа нажмите Добавить поле.
2. В поле Название впишите подпись для людей, например ID. Её видно при выборе переменных, а новое поле карточки получает её как название.
3. Впишите Путь в ответе, например account.id.
4. Выберите, куда сохранить: в переменную, в поле контакта или в список контакта. Для списка впишите имя поля, например crm_accounts, и колонку, например id.
5. Повторите для других значений, например логина по пути account.username.

Путь в ответе:

• путь через точку: data.account.id; элемент списка указывается номером с нуля: items.0.id;
• @status сохраняет код ответа;
• пустой путь сохраняет весь ответ.

Куда сохранить:

• в переменную: значение доступно как $vars.<имя> в следующих шагах этого запуска;
• в поле контакта: в поле карточки клиента с этим ключом. Если такого поля нет, а Название задано, поле появится в настройках полей контакта;
• в список контакта: запись добавится в поле карточки типа Список записей.

Имя пишется латинскими буквами, цифрами и _ и не начинается с цифры. Колонка пишется строчными латинскими буквами, цифрами и _. Значения сохраняются только при успешном ответе.

Как работает сохранение в список контакта:

• строки с одним и тем же полем собираются в одну запись: id и username нового аккаунта попадают в одну строку списка;
• новая запись добавляется к списку;
• если в списке уже есть запись с тем же значением уникальной колонки, она обновляется;
• если это значение уже есть у другого клиента, шаг завершается ошибкой: … уже привязан к другому контакту;
• если поля нет, оно создаётся, а первая колонка становится уникальной.

После каждого вызова в $vars.http_status лежит код ответа, а в $vars.http_error текст ошибки.

Выполнять один раз

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

1. В разделе Выполнять один раз включите Не отправлять повторно для того же ключа.
2. В поле Ключ впишите шаблон, который однозначно называет операцию: crm_account:$contact.id.
3. На холсте соедините выход Уже выполнено со следующим шагом, если нужно.

Как работает:

• если операция с таким ключом уже прошла успешно, запрос не отправляется. Workflow идёт по выходу Уже выполнено, а если он ни с чем не соединён, по выходу Успех. Переменные из прошлого раза восстанавливаются;
• отметка ставится только после успеха, после ошибки операцию можно повторить;
• если такая операция сейчас идёт в другом запуске или её результат неизвестен, запрос не отправляется и шаг завершается ошибкой. Проверьте в вашей системе, что произошло;
• если для ключа не хватает переменной, шаг завершается ошибкой: Ключ операции не собрался.

Выполненные операции видны в карточке клиента, в разделе Внешние операции. Там же можно сбросить отметку, например если запись в вашей системе удалили вручную. Подробнее в статье Журнал запусков.

Пробный запрос

Пробный запрос отправляется из редактора и показывает ответ системы. Ваша система выполнит его как настоящий.

1. Раскройте Пробный запрос.
2. Если в запросе есть переменные клиента, вставьте в поле Диалог для проверки ссылку на диалог или его ID.
3. Нажмите Отправить.

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

Пример: создать аккаунт в CRM по кнопке

1. Запуск: Кнопка в диалоге, название Создать аккаунт в CRM.
2. Запросить данные: поля Логин, Телефон, Telegram и Тариф (выбор из списка), получатель Тому, кто запустил (поставил тег).
3. Внешний вызов: подключение Ваша CRM, POST /accounts, тело полями из формы, Выполнять один раз с ключом crm_account:$contact.id, сохранить account.id в список контакта crm_accounts, колонка id.
4. От выхода Успех: Сообщение клиенту с текстом Ваш логин: $vars.username.
5. От выхода Ошибка: Уведомить сотрудника, вид Ошибка — красное, текст $vars.http_error.
6. В настройках запуска, в разделе Дополнительно, выключите Останавливать, когда отвечает оператор.

Показать ответ сотруднику

Пример: сотрудник видит баланс клиента из вашей системы.

1. Запуск: Кнопка в диалоге, в поле Показывать выберите Если заполнено и поле с ID клиента в вашей системе.
2. Внешний вызов: GET /clients/$contact.custom.crm_id, в Сохранить из ответа пустой путь в переменную info.
3. Показать сотруднику: переменная info.

Окно откроется у того, кто нажал кнопку. Подробнее о шаге в статье Шаги workflow.

Справка

Вид тела запроса

Тело бывает у методов POST, PUT и PATCH.

• Поля (по умолчанию): JSON собирается из строк с именем и значением;
• Вручную (JSON): JSON целиком. Переменные ставьте в кавычки: "name": "$contact.name";
• Форма: name=$contact.name&phone=$contact.phone;
• Текст: уходит как есть;
• Без тела.

В режиме Поля точка в имени создаёт вложенный объект: client.phone превращается в {"client": {"phone": …}}. Типы полей:

• Текст: строка;
• Число: можно с запятой. Если значение не число, шаг завершится ошибкой;
• Да/нет: true для true, 1, да, yes; false для false, 0, нет, no и пустого значения;
• Как есть: значение одной переменной уходит без изменений, объект остаётся объектом.

Если переменной нет, в поле уходит null. JSON, написанный в режиме Вручную (JSON), при переключении на Поля раскладывается на поля.

Параметры адреса и заголовки

• Параметры адреса добавляются после ? парами имени и значения, например phone и $contact.phone. Значения кодируются автоматически.
• Заголовки добавляют свои заголовки к запросу. Если имя заголовка похоже на ключ доступа, редактор предложит хранить ключ в подключении.

Надёжность

• Ждать ответа, сек: от 1 до 60, по умолчанию 15.
• Повторов при сбое: от 0 до 3, по умолчанию 2. Запрос повторяется, если нет связи или пришёл ответ 429 или 5xx.

Адреса внутренней сети недоступны, переадресации не выполняются, ответ больше 1 МБ не принимается.

Выходы

Если выход Ошибка ни с чем не соединён, запуск останавливается со статусом Ошибка. Если соединён, workflow идёт дальше по нему: например, уведомляет сотрудника с текстом $vars.http_error.

После вызова в ленте диалога появляется строка Workflow отправил данные во внешнюю систему. Если система не приняла запрос, строка будет такой: Внешняя система не приняла данные workflow (код …).