Блоки являются основой омниканальных сценариев. Они определяют, какие действия и в каком порядке будут происходить.
В редакторе доступно пять категорий блоков:
В этой статье подробно разберем блок «API-запрос» из категории «Действия».
Блок «API-запрос» позволяет интегрировать внешние сервисы к омниканальным сценариям Unisender, расширяя возможности автоматизации.
С его помощью вы сможете:
- передавать данные во внешние системы, которые поддерживают API;
- интегрировать собственные сервисы, например, интернет-магазин или мобильное приложение;
- сохранять полученные данные и использовать их для персонализации писем;
- выполнять проверки, например, узнать статус заказа, результат оплаты или доступность отправки.
Принцип работы API-запроса
Блок отправляет запрос по указанному URL, передает данные во внешнюю систему и получает ответ.
Полученный ответ сохраняется в виде шаблона и становится доступен в других блоках сценария, например для подстановки в письмо, проверки значений в условиях или передачи данных дальше по сценарию.
Как настроить API-запрос
Перейдите в раздел «Сценарии», откройте нужный или создайте новый сценарий, выберите триггер, затем добавьте на рабочую область блок «API-запрос» из категории «Действия».
Выберите HTTP-метод. Он определяет, что именно будет делать запрос. По умолчанию выбран POST.
Укажите полный URL-адрес API-запроса, к которому будет выполняться запрос. Поле не может быть пустым. В значении можно использовать подстановки из данных сценария.
Примеры URL с подстановками:
| С ID контакта в пути:
https://api.service.ru/users/{{ contact.id }}/events С параметрами запроса: https://api.service.ru/search?q={{ order.product_name }}&limit=10 С данными из другого API-блока: https://api.partner.io/sync?ref={{ external_api.transaction_id }} |
Заголовки — это дополнительные параметры запроса. По умолчанию добавлен заголовок "Content-Type: application/json", он указывает формат передаваемых данных, его нельзя удалить.
При необходимости можно добавить любое количество дополнительных заголовков. Каждый заголовок задается парой «Ключ / Значение».
Пример настройки заголовков:
| Поле «Ключ» (имя заголовка) | Поле «Значение» | Для чего используется |
| X-API-Key | sk_live_7f8a9b0c1d2e | Простая API-авторизация стороннего сервиса |
| Accept | application/json | Указание формата, который ожидает получить сервер |
| X-Campaign-ID | {{ campaign.id }} | Передача данных из сценария прямо в заголовок |
Чтобы добавить заголовок нажмите на кнопку «Добавить заголовок». Чтобы удалить заголовок, наведите на него курсор и нажмите на крестик.
В Теле запроса добавьте данные, которые нужно передать во внешнюю систему, например, email, имя клиента, список товаров и т.п. Тело запроса задается в формате JSON.
Редактор можно раскрыть в увеличенный вид.
В значениях можно использовать подстановки, для этого откройте выбор данных через фигурные скобки в панели инструментов.
Ключ блока — это уникальный идентификатор блока «API-запрос», который позволяет другим блокам сценария получать данные из его ответа. Полученные данные можно использовать в других частях сценария.
Например:
- Название блока: "Проверка доставки"
- Ключ блока: ApiZapros24
- Использование: {{ ApiZapros24.status }}
Для подстановки данных используется шаблонизатор Liquid. Это язык шаблонов, с помощью которого можно подставлять значения из JSON-ответа.
| Тип данных | Пример в JSON-ответе | Liquid-подстановка |
| Поле | {"status":"active"} | {{ ApiZapros24.status }} |
| Вложенный объект | "user": {"name": "Ivan"} | {{ ApiZapros24.user.name }} |
| Массив | "items": ["A", "B"] | {{ ApiZapros24.items[0] }} |
| Значение по умолчанию | поле отсутствует | {{ ApiZapros24.price | default: "0" }} |
| Первый элемент массива | "blocks": [...] | {{ ApiZapros24.blocks.first }} |
| Последний элемент массива | "blocks": [...] | {{ ApiZapros24.blocks.last }} |
Используйте конструкции .first и .last, если не знаете точное количество элементов в массиве или когда нужно получить крайние значения (например, последний заказ, первое событие, последняя транзакция и т.д.).
Подробно про шаблонизатор Liquid можно прочитать в документации (на русском языке).
Ключ генерируется автоматически на основе названия блока. Его можно изменить вручную.
Правила для ключа:
- только латинские буквы, цифры и нижнее подчеркивание;
- ключ должен начинаться с буквы;
- ключ должен быть уникальным среди всех блоков «API-запрос» в сценарии.
Если ключ совпадает с уже существующим, система покажет ошибку и напомнит, что ключ должен быть уникальным.
После настройки «API-запроса» соберите оставшуюся часть сценария с помощью готовых блоков, чтобы выстроить логику коммуникации.
Когда все будет готово, запустите сценарий.
Тестовый запрос и настройка ответа
Здесь можно указать формат данных, ожидаемых от внешней системы, для их последующего использования в сценарии с помощью подстановок.
Заполнить шаблон можно двумя способами:
- Вручную. Для этого введите ожидаемую структуру ответа в редакторе кода.
- Через тестовый запрос. Нажмите кнопку «Отправить тестовый запрос». Система выполнит запрос с указанными методом, URL, заголовками и телом. Полученный ответ автоматически подставится в шаблон.
Если запрос был успешным появится уведомление с результатом и кнопкой «Скопировать ответ».
Если запрос завершился с ошибкой, появится уведомление с описанием ошибки и кнопкой «Скопировать ответ».
Если запрос не дошел до внешнего сервиса (например, указан неверный URL), система покажет отдельное уведомление с описанием причины.
Как использовать данные ответа в сценарии
Выполните тестовый запрос или заполните шаблон вручную.
Найдите ваш API-запрос по уникальному ключу блока. Найти API-запрос по ключу можно в других блоках сценария, где требуется использовать данные из ответа этого API-запроса. Например, в блоках, где нужно подставить данные из ответа (в письме или условии), или в интерфейсе редактора, где ключ блока отображается в списке доступных данных для подстановки.
Выберите нужное поле из ответа по нажатию на строку.
Вставьте путь в нужное место, например, в тело письма.
Если возникли ошибки
В режиме статистики можно посмотреть количество ошибок. Для этого нажмите на ошибку в блоке, чтобы посмотреть детали запроса и ответа.
Обратите внимание:
Редактор кода в режиме статистики недоступен для изменений.
Если запрос не выполняется или данные не подставляются корректно, важно определить, на каком именно этапе возникли ошибки.
Далее рассмотрим основные причины и способы их устранения.
Запрос не выполняется. В этом случае необходимо:
- проверить корректность URL;
- проверить тело запроса содержит валидный JSON;
- проверить заголовки и подстановки.
Если использование полученных данных из «API-запроса» через подстановки не срабатывают, проверьте, что ключ блока уникален и не содержит ошибок, а также убедитесь, что сценарий запущен.
Полезные ссылки
Как создать и запустить триггерный сценарий
Использовать API-триггер в омниканальных сценариях
Блоки триггеров
Блоки сообщений
Блоки действий
Блоки логики сценариев
Действия над блоками
