Ця сторінка призначена для розробників, які інтегрують бекенд компанії зі Skava. Створення та випуск елемента API описано на сторінці Користувацькі елементи: інтерфейси API; тут ми розглядаємо все, що має відбуватися на іншому кінці з'єднання.

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

Загальний огляд процесу

1. Адміністратор компанії створює елемент API у Skava: форму, а також адресу вашого бекенду, метод і токен.
2. Хтось у чаті заповнює форму та надсилає її.
3. Skava викликає ваш бекенд і надсилає заповнені значення у форматі JSON.
4. Ваша відповідь стає карткою у чаті.
5. За бажанням ви можете пізніше повідомляти про нові стани через зворотний виклик. Кожне повідомлення стає новою карткою, попередня залишається.

Вимоги до вашого бекенду

• HTTPS. Тільки https://, без http, без облікових даних у адресі, не більше 2000 символів.
• Доступний з публічної мережі. Хост має розв'язуватися виключно на публічні IP-адреси. Локальний хост, приватні мережі, локальні посилання та метадані хмари відхиляються, і це перевіряється при кожному виклику.
• Фіксована адреса. Skava розв'язує хост один раз і прив'язує з'єднання до цієї IP-адреси. Зміна DNS під час виклику не матиме ефекту.
• Без перенаправлень. Перенаправлення 301 на «правильну» адресу вважається помилкою. Введіть кінцеву адресу одразу.
• Час відповіді. Тайм-аут налаштовується для кожного елемента і має жорсткий ліміт у 30 секунд. Якщо потрібен більший час, відповідайте негайно, а результат повідомте пізніше через зворотний виклик.
• Розмір відповіді. Skava читає не більше 256 КіБ.
• Content-Type. Тіло запиту обробляється лише з application/json.

Запит, який ви отримуєте

Метод — GET, POST, PUT або PATCH залежно від елемента. Для POST, PUT та PATCH значення надходять у тілі JSON, для GET — як параметри запиту.

Аутентифікація — це один заголовок, назва та префікс значення якого налаштовані в елементі, зазвичай Authorization з префіксом Bearer . Токен зберігається у зашифрованому вигляді на нашому боці. Заголовки host, content-length, content-type, cookie та accept-encoding не можна встановлювати.

Тіло — це плоский об'єкт. Ключі обирає розробник елемента; вкладеність з'являється лише там, де він додав таблицю або вибір продукту:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Три ключі завжди надаються нами, тому не використовуйте їх самостійно:

• locale: мовний код користувача. Відповідайте цією мовою; ми не перекладаємо ваші тексти.
• callback_url та callback_token: зворотний виклик для цього одного взаємодії, див. нижче. Вони присутні лише коли виклик надходить із чату.

Поля контексту, такі як name, company, project або subchat, заповнюються сервером самостійно на основі каналу, у якому запущено елемент. Змінений клієнт не може вказати іншу назву проекту.

Відповідь: формат картки

Відповідь з кодом 2xx та об'єктом card. Саме це стає карткою в чаті:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

• v (обов'язково): ціле число 1. У текстовому вигляді ("1") воно відхиляється. Без цього поля відповідь не вважається карткою, і застосовується налаштоване в елементі відображення відповіді.
• title: заголовок картки.
• state: лише колір і відтінок іконки, одне з ok, pending, warn, error. Невідоме значення замінюється на ok, і ви отримуєте підказку.
• status_text: довільний текст, який ми не інтерпретуємо. Він розміщується вгорі картки і також відображається у списку чатів та в сповіщенні.
• fields: список label та value. Максимум 20 записів, label до 80 символів, value до 200, title та status_text по 120 кожен. Занадто довгі значення скорочуються, а не відхиляються: замовлення не повинно провалитися через дрібницю.
• icon: див. нижче.

Що робить Skava з вашим текстом перед відправкою в чат: видаляє переноси рядків та керуючі символи (право-ліворуч символ міг би перевернути відображення суми), замінює зворотні апострофи та знешкоджує все, що починається з [SKAVA:. Останнє запобігає тому, щоб значення картки було сприйнято як інший елемент чату, наприклад, запит на оплату.

Посилання в полях, HTML та зображеннях не можна встановити. Чат — це довірене середовище, а клікабельна адреса з чужого бекенду була б закликом до створення підробленої сторінки входу.

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

Іконки

Завдяки icon картка отримує власний маркер у заголовку. Два способи:

Назва з вбудованого набору: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Або власний SVG у вигляді рядка. Skava бере з нього лише геометрію (path, circle, ellipse, rect, line, polyline, polygon з їх числовими атрибутами) і будує власне зображення. Скрипти, стилі, зовнішні посилання, foreignObject та атрибути подій відкидаються; наявність doctype або сутності призводить до відмови; файл може мати розмір не більше 8 КіБ і містити не більше 16 фігур. Колір, товщину обводки та розмір задає Skava, тому іконка не може видавати себе за елемент керування. Працюйте з сіткою 24 на 24.

Без icon залишається маркер за замовчуванням.

Зворотний виклик: повідомлення про подальші стани

Виклик містить callback_url та callback_token. Використовуйте їх для повідомлення про нові стани пізніше:

POST <callback_url> з Authorization: Bearer <callback_token> та Content-Type: application/json, тіло не більше 32 КіБ:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Окрім картки є три необов'язкові значення:

• seq: ваш власний лічильник. Повідомлення з меншим або рівним значенням відкидається, щоб два повідомлення не могли обігнати одне одного. Без seq перемагає останнє отримане повідомлення.
• final: завершує взаємодію. Токен стає недійсним, і подальші картки не з'являються. Також допустимо у першій відповіді для потоків без подальших кроків.
• notify: встановіть false, щоб опублікувати картку безшумно, без лічильника непрочитаних повідомлень і без сповіщення. Це підходить для проміжних кроків, які не повинні будити користувачів. Без цього параметра картка є звичайним повідомленням.

Кожен звіт стає окремою карткою в чаті, попередня залишається. Так можна зрозуміти, який стан було повідомлено. З цього випливає рекомендація: надсилайте лише те, що змінилося. Картка, яка в четвертий раз повторює номер замовлення, позиції та загальну суму, є лише шумом для читача.

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

Відповіді, на які варто реагувати

• 200 з {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Прочитайте підказки: вони пояснюють, що було скорочено або видалено.
• 401: невірний токен або ідентифікатор взаємодії. Не повторюйте спробу.
• 410: взаємодію закрито або вона застаріла. Не повторюйте спробу.
• 422: картку неможливо використати, причина вказана в hints. Спочатку виправте помилку.
• 400 некоректний JSON, 413 занадто великий розмір, 429 занадто багато запитів (повторіть спробу з затримкою), 500 наша помилка, повторіть спробу пізніше.

Приклад 1: замовлення з історією статусів

Крок 1, запит до вашого бекенду:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Крок 2, ваша миттєва відповідь:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

У чаті з'являється картка з іконкою посилки, статусом та введеними користувачем даними.

Крок 3, пізніше під час комплектації:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

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

Крок 4, при відправці:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Ця картка може прокинути когось, тому немає notify: false.

Крок 5, при доставці:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

З final взаємодія завершена і токен більше не працює.

Приклад 2: дія без подальших кроків

Не у всіх сценаріях є історія. Елемент із одним полем, який передає дані у вашу систему, потребує лише однієї відповіді:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true має тут вирішальне значення: інакше взаємодія залишиться відкритою на 90 днів із дійсним токеном, навіть якщо ви більше нічого не звітуйте.

Вибір товару з каталогу

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

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Оскільки ключ є безкоштовним, шукайте перший список із такою структурою, а не з фіксованою назвою. Перед відправкою Skava перевіряє, чи справді кожен номер існує в каталозі цієї компанії (не більше 50 позицій). У картці позиції відображаються списком із зображенням товару, назвою та кількістю.

Тестування

• Ping у редакторі елементів надсилає простий запит HEAD без токена та даних. Відповідь може бути будь-якою: будь-яка відповідь HTTP означає, що ресурс доступний.
• Тестовий запит виконує реальний виклик із прикладними значеннями, навіть якщо елемент ще є чернеткою, і показує запит, відповідь та повідомлення валідатора картки.
• Попередній перегляд на сусідній вкладці: вставте ваш JSON-відповідь, перевірте, і ви побачите готову картку разом із підказками. Перевірка виконується на сервері тим самим кодом, що й у продакшені.
• Приклад сервера: повний приклад постачальника працює на api.skava.io і використовує все описане вище. Його вихідний код знаходиться в репозиторії в папці example_order_server/, близько 600 рядків чистого стандартного бібліотечного коду, призначеного для копіювання.

Що ще варто знати

• Карточка є звичайним повідомленням у чаті. Вона з'являється в результатах пошуку, її можна цитувати, і вона залишається в історії.
• Вона надсилається системним відправником, а не від імені облікового запису вашої компанії. Вона все одно з'являється на боці того, хто запустив елемент, а в заголовку вказано, чия система виконує запис.
• Хто може його запускати, налаштовується на самому елементі: лише члени компанії або також сторонні особи, які мають спільний чат. Коли ваша компанія залишає чат, дозвіл автоматично припиняється.
• Елемент API з простроченим токеном перебуває в неактивному стані і навіть не відображається в меню, доки адміністратор не збереже новий токен.

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

Створення та публікація: Користувацькі елементи: інтерфейси API. Заповнювані документи замість інтерфейсів: Користувацькі елементи: документи.