Skava Skava / Wiki

Власні елементи: API

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

i

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

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

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

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

Тестування: Ping та тестовий запит

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

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

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

Створення та публікація

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

!

Опубліковані інтерфейси є незмінними. Це навмисно: після публікації ніхто не зможе таємно замінити цільову адресу або токен. Якщо потрібно щось змінити, створіть нову версію.

Безпека

i

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

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

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

  1. У чаті натисніть Плюс внизу і виберіть Користувацький елемент.
  2. Оберіть потрібний шаблон або інтерфейс зі списку.
  3. Заповніть форму і натисніть Надіслати.
  4. Результат з'являється у вигляді картки в чаті: він видимий усім учасникам чату.
Веб-додаток Skava: меню «Плюс» у полі введення чату з пунктами «Прикріпити файл», «Фото/відео», «Створити завдання», «Створити позицію послуги» та «Користувацький елемент».
Крок 1: через меню Плюс у чаті виберіть Користувацький елемент.
Веб-додаток Skava: діалогове вікно «Користувацький елемент» над чатом, де пропонується опублікована дія API «Замовлення матеріалів»; картки результатів вже надіслані у фоновому режимі.
Крок 2: виберіть потрібний шаблон або інтерфейс: тут це дія API Замовлення матеріалів.
Вебдодаток Skava: заповнювана форма дії API «Замовлення матеріалів» із полями номер статті, опис, кількість, одиниця виміру, бажана дата доставки та примітка, а також нотатка про автоматично включені значення.
Крок 3: заповніть форму. У нотатці внизу показано, які значення додаються автоматично.
Вебдодаток Skava: картка результату дії API «Замовлення матеріалів» у чаті зі статусом 200, введеними значеннями та відповіддю бекенду (номер замовлення, статус, дата доставки), а також розкриваними вихідними даними.
Крок 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.

Споріднене

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

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

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

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

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

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

Яка різниця між «Ping» та «Тестовим запитом»?

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

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

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

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

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

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

Опубліковані інтерфейси навмисно є незмінними, щоб після публікації ніхто не міг підмінити цільову адресу або токен. Для змін створюється нова версія.