Skava Skava / Wiki

Користувацькі елементи: API

Інтерфейс API це форма, значення якої Skava надсилає у форматі JSON на вказану вами адресу (ваш бекенд). Так ви можете безпечно інтегрувати Skava зі своїми системами.

i

Ви керуєте інтерфейсами API у Webapp у розділі Custom Elements → перемикач API Interfaces. Створення та редагування доступні лише адміністраторам компанії; опубліковані інтерфейси можуть запускати всі учасники компанії.

Налаштування інтерфейсу 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: вкладка «Поля» інтерфейсу API. Зверху автоматично включені контекстні значення (ім'я користувача, компанія, проєкт тощо), нижче користувацькі поля з JSON-ключами, праворю прев'ю форми та живий перегляд JSON.
Вкладка Fields: кожне поле отримує JSON-ключ. Зверху автоматично додаються контекстні значення, такі як користувач, компанія та назва проєкту. Праворю ви бачите форму та JSON у реальному часі: саме те, що надсилається на ваш бекенд.
Вебдодаток Skava: вкладка «Endpoint» інтерфейсу API з полями для URL, методу POST, тайм-ауту, заголовка автентифікації, префікса значення Bearer та полем для введення зашифрованого токена.
Вкладка Endpoint: цільова адреса (лише HTTPS), метод, тайм-аут, а також заголовок автентифікації та префікс значення. Токен зберігається у зашифрованому вигляді і ніколи не передається клієнтам.
Веб-додаток Skava: вкладка «Перегляд» інтерфейсу API. Визначено поле відповіді з JSON-ключем Success, праворуч показано попередній перегляд того, як результат виглядатиме в чаті.
Вкладка Перегляд (необов'язкова): визначте за шляхом, які значення з відповіді бекенду відображатимуться. Праворуч Skava формує картку результату на їхній основі, точно так, як вона з'явиться пізніше в чаті.

Безпечно зберігайте токен

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

Тестування: Ping і Test Request

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

Як адміністратор, ви можете запустити обидва, перебуваючи в режимі чернетки, щоб перевірити інтеграцію перед публікацією.

Веб-додаток Skava: вкладка «Тест» інтерфейсу API з кнопками «Ping» та «Тестовий запит», результатом Status 200 OK, часом відповіді та повною JSON-відповіддю від бекенду.
Вкладка Тест: Ping та Тестовий запит поруч. Тут зі статусом 200, часом відповіді та повною відповіддю бекенду у форматі JSON.

Складання та публікація

Кожний інтерфейс створюється як чернетка і може вільно редагуватися. Коли все готово, ви публікуєте його за допомогою кнопки Опублікувати.

!

Після публікації цільова адреса, метод, поля, заголовок автентифікації та обмеження часу фіксуються. Це свідоме рішення: ніхто не може тихо перенаправити дані в інше місце. Лише три параметри залишаються змінними, бо операційна команда в них потребує: токен і його термін дії (щоб замінити прострочений або використаний токен) та аудиторія, тобто чи може інтерфейс запускати лише ваша команда, чи також партнерські компанії в чаті. Для всіх інших змін створюйте нову версію.

Безпека

i

Щоб запобігти зловживанням інтерфейсом, діють суворі правила: дозволені лише адреси HTTPS, і адреса має вказувати на публічну цільову адресу: внутрішні адреси (наприклад, localhost, приватні мережі або метадані хмари) відхиляються. Skava перевіряє це при кожному виклику, з'єднується саме з перевіреною адресою, не слідує за перенаправленнями та обмежує час очікування і розмір відповіді.

Як команда використовує опублікований інтерфейс

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

  1. У чаті натисніть Плюс внизу та оберіть потрібний елемент, наприклад Замовлення матеріалів.
  2. Заповніть форму та натисніть Надіслати.
  3. Результат з'являється у вигляді картки в чаті, доступної всім учасникам розмови.
Вебдодаток Skava: заповнювана форма дії API «Замовлення матеріалів» із полями артикул, опис, кількість, одиниця виміру, бажана дата доставки та примітка, а також примітка про автоматично включені значення.
Крок 3: заповніть форму. Примітка внизу вказує, які значення включаються автоматично.
Вебдодаток Skava: картка результату дії API «Замовлення матеріалів» у чаті зі статусом 200, введеними значеннями та відповіддю бекенду (номер замовлення, статус, дата доставки), а також розгортанням сирих даних.
Крок 4: картка результату в чаті, що містить введених дані та відповідь вашого бекенду.

Дайте ШІ створити елемент

Як адміністратор компанії, вам не обов’язково користуватися редактором самостійно. Просто скажіть асистенту Skava в чаті, наприклад: «Створи для мене форму замовлення для мого каталогу з кількістю та адресою доставки». На основі цього він створить чернетку, пізніше зможе змінювати поля по одному, а також знає ваш завантажений каталог товарів: для замовлень він пропонує вибір товару замість текстового поля для номера статті.

Він також може налаштувати: кінцеву точку та метод, а також аудиторію («тільки члени компанії» або «також зовнішні учасники в тому ж чаті»). Щодо аудиторії, він спершу запитує, а не просто встановлює параметр, оскільки це визначає, хто може виконувати дії ззовні.

Чого він явно не торкається: токен доступу. Він ніколи не запитує його і ніколи не приймає, бо повідомлення в чаті зберігаються. Ви вводите його самостійно в редакторі, інакше жодного запиту не надсилається. І він не може опублікувати: останній крок залишається за вами, тож нічого не стане видимим для клієнтів без перевірки.

Хто може його запускати

Вкладка «Endpoint» вказує, хто може використовувати елемент. За замовчуванням це члени вашої компанії. Другий параметр відкриває доступ для зовнішніх учасників, але лише в чаті, де присутній хтось із вашої компанії: саме той випадок, для якого це призначено, коли клієнт замовляє у вас. Коли ваша компанія виходить із чату, дозвіл автоматично припиняється.

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

Після завантаження каталогу товарів, 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.

Пов'язані матеріали

Ви натомість хочете створити шаблон документа для заповнення? Дивіться Кастомні елементи: Документи.

Часті запитання

Що таке API-інтерфейс у Skava?

Форма, значення якої Skava надсилає у форматі JSON на вказану вами адресу (ваш бекенд): зручно для підключення Skava до власних систем.

Хто має право створювати та запускати API-інтерфейси?

Створення та редагування доступні лише адміністраторам компанії. Опублікований інтерфейс можуть запускати всі учасники компанії.

Яка різниця між "Ping" та "Test Request"?

Ping перевіряє лише доступність адреси: без токена та без даних. Test Request надсилає тестові дані разом із токеном і показує повну відповідь.

Чи безпечний мій API-токен?

Так. Токен зберігається в зашифрованому вигляді і ніколи не передається клієнтам. Додаток показує лише наявність токена та дату його закінчення.

Які адреси дозволені як точки кінцевого доступу?

Лише публічно доступні адреси https://. Внутрішні цілі, такі як localhost, приватні мережі або хмарні метадані, відхиляються: це захищає від зловживань інтерфейсом.

Чому я більше не можу змінити опублікований інтерфейс?

Цільова адреса, метод, поля та заголовок автентифікації фіксуються після публікації, щоб ніхто не міг тихо перенаправити потік даних. Токен, його строк дії та аудиторія (лише власна команда або також партнерські компанії) залишаються змінюваними; саме так ви замінюєте прострочений токен. Для всіх інших змін створюйте нову версію.