Пользовательские элементы: API

Интерфейс API представляет собой форму, значения которой Skava отправляет в формате JSON по указанному вами адресу (вашему бэкенду). Так вы можете безопасно связать Skava с собственными системами.

Настройка интерфейса API

Интерфейс состоит из полей ввода (они формируют JSON), целевого адреса и аутентификации.

1. Создание полей: Каждое поле получает ключ JSON. Справа вы видите предпросмотр JSON в реальном времени, который отправляется на ваш бэкенд именно в таком виде.
2. Адрес (URL): адрес https:// вашего бэкенда. Допускаются только HTTPS и общедоступные адреса (см. раздел «Безопасность» ниже).
3. Метод: POST (по умолчанию), PUT, PATCH или GET. При использовании GET значения добавляются в качестве параметров запроса, а не отправляются в теле запроса.
4. Аутентификация: Укажите имя заголовка (например, Authorization) и префикс значения (например, Bearer ), затем сохраните токен. При необходимости установите дату истечения срока действия.
5. Поля ответа (необязательно): Определите по пути, какие значения из ответа бэкенда следует отображать: например, order.id или items[0].sku.
6. Проверьте с помощью Ping и Test Request, затем Release.

Безопасное хранение токена

Токен хранится в зашифрованном виде и никогда не возвращается клиентам: приложение показывает только наличие токена и срок его действия. При отправке Skava добавляет токен на стороне сервера в настроенный заголовок. Если указан срок действия, Skava отклоняет запрос после истечения срока и просит обновить токен.

Тестирование: Ping и Test Request

• Ping: быстрая проверка доступности. Проверяет только отвечает ли ваш адрес, не отправляя при этом токен или данные формы. Показывает доступность, статус и время ответа. Идеально подходит для первого шага.
• Тестовый запрос: полноценная проверка: отправляет образец данных, включая токен, на ваш адрес и показывает полный ответ, а также извлеченные поля ответа.

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

Черновик и публикация

Каждый интерфейс сначала создаётся как черновик и может свободно редактироваться. Когда всё готово, вы публикуете его через Публикация.

Безопасность

Как команда использует опубликованный интерфейс

После публикации интерфейса все участники компании могут запускать его прямо из чата, без редактора. Нет общего входа и промежуточных диалогов: каждый опубликованный элемент находится в меню «Плюс» под своим названием, с логотипом компании, которая его предлагает.

1. В чате нажмите Плюс внизу и выберите нужный элемент, например Заказ материалов.
2. Заполните форму и нажмите Отправить.
3. Результат появляется в чате в виде карточки, видимой всем участникам чата.

Попросите ИИ создать элемент

Как администратор компании, вам не обязательно использовать редактор самостоятельно. Просто скажите ассистенту Skava в чате, например: «Создай форму заказа для моего каталога с количеством и адресом доставки». Он создаст из этого черновик, позже сможет менять поля по одному и знает ваш загруженный каталог статей: для заказов он предложит выбор товара, а не текстовое поле для номера статьи.

Он также может настроить: эндпоинт и метод, а также аудиторию («только члены компании» или «также внешние участники в том же чате»). Для аудитории он сначала спросит, а не просто установит значение, так как это определяет, кто может запускать элемент извне.

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

Кто может запускать

Вкладка «Эндпоинт» указывает, кто может использовать элемент. По умолчанию это члены вашей компании. Вторая настройка открывает доступ для внешних участников, но только в чате, где присутствует кто-то из вашей компании: именно тот случай, для которого это предназначено, когда клиент делает заказ у вас. Когда ваша компания покидает чат, разрешение автоматически прекращается.

Товары из вашего каталога

После загрузки каталога товаров в конструкторе появляется блок выбора товара. Настраивать ничего не нужно: список и есть ваш каталог. Заказчик ищет в нём товар, видит изображение, название и артикул, а ваш бэкенд получает артикул. Skava отклоняет артикулы, которых нет в вашем каталоге. Для указания количества добавьте рядом обычное числовое поле.

Определите карточку самостоятельно

Ваш бэкенд решает, что написать в карточке. Skava проверяет только структуру, размер и безопасность, но не смысл: она не знает ни статусов заказа, ни имён полей. Для этого ответьте объектом card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v должно быть целым числом 1. Без этого ответа не считается карточкой, и применяется маппинг ответа, настроенный в элементе.
• state определяет только цвет и иконку: ok, pending, warn или error. Весь смысловой контент передается в status_text как свободный текст.
• fields представляет собой список пар «метка и значение», максимум 20 записей. Слишком длинные значения укорачиваются, а не отклоняются, поэтому заказ не падает из-за мелкой детали.

Ввод пользователя принадлежит серверу: он остается неизменным независимо от того, что отправляет ваш бэкенд. Это запись в чате о том, что было фактически отправлено.

Сообщение о статусе позже

При запуске элемента Skava отправляет два дополнительных значения: callback_url и callback_token. Позже сообщите о новом состоянии по этому адресу, и в чате появится новая карточка, даже на телефоне, пока кто-то смотрит. Предыдущая карточка остается, поэтому понятно, какое состояние было сообщено. Отправьте тот же объект card, что и выше, через POST с заголовком Authorization: Bearer <callback_token>. Три необязательных значения передаются рядом с карточкой:

• seq: ваш собственный счётчик. Отчёт с меньшим или равным значением отбрасывается, поэтому два отчёта не могут перескочить друг друга.
• final: завершает взаимодействие. Токен становится недействительным, а карточка фиксируется.
• notify: установите false, чтобы опубликовать карточку без звука, без счётчика непрочитанных и без уведомления. Подходит для промежуточных шагов, которые не должны будить никого. Без этого параметра карточка является обычным сообщением.

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

Skava отвечает кодом 200 и списком hints, если что-то было сокращено или отброшено, и кодом 422, если карточка оказалась непригодной. Взаимодействие принимает отчёты в течение 90 дней.

Карточки отправляются системным отправителем Skava, а не тем, кто запускал элемент, и не от имени вашей компании. В заголовке карточки указано, какая система её отправила.

Полный пример для копирования находится в репозитории по пути example_order_server/ и доступен на api.skava.io.

Связанные материалы

Если вам нужен шаблон документа с заполняемыми полями, см. Кастомные элементы: Документы.

Часто задаваемые вопросы