Пользовательские элементы: 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 и тестовый запрос

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

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

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

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

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

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

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

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

Позвольте ИИ создать элемент

Как администратор компании вам не обязательно пользоваться редактором самостоятельно. Попросите помощника 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.

См. также

Вам нужно создать шаблон документа с полями для заполнения? Перейдите к разделу Пользовательские элементы: Документы.

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