Skava Skava / Wiki

Повръзка на персонализирани елементи за разработчици

Тази страница е за разработчици, които свързват бекенда на компанията със Skava. Как се създава и публикува API елемент е описано в Персонализирани елементи: API интерфейси; тук разглеждаме всичко, което трябва да се случи на другия край на връзката.

Идеята в едно изречение: Skava не познава вашата област. Тя познава точно един формат, картата. Вие решавате какво да съдържа, ние само проверяваме формата, размера и безопасността. Поръчка за материали е един пример; следващата компания събира обратна връзка от потребителите, а тази след нея архивира снимка от обекта в собствените си записи.

Процесът на преглед

  1. Администратор на компанията създава API елемент в Skava: формуляр плюс адресът на вашия бекенд, метод и токен.
  2. Някой в чата попълва формата и я изпраща.
  3. Skava извиква вашия backend и изпраща попълнените стойности като JSON.
  4. Вашият отговор става карта в чата.
  5. По желание по-късно докладвате нови състояния чрез callback. Всеки доклад става нова карта, а предишната остава.

Изисквания към вашия backend

  • HTTPS. Само https://, без http, без данни за вход в адреса, максимум 2000 знака.
  • Достъпен публично. Хостът трябва да се разрешава изключително към публични IP адреси. Локалните хостове, частните мрежи, link-local адресите и облачната метаданни се отхвърлят, а това се проверява при всяко извикване.
  • Фиксиран адрес. Skava разрешава хоста веднъж и фиксира свързването към този IP. Промяна в DNS по време на извикването няма ефект.
  • Без пренасочвания. Пренасочване 301 към „правилния“ адрес се брои за неуспех. Въведете крайния адрес веднага.
  • Време за отговор. Таймаутът се настройва за всеки елемент и е ограничен до 30 секунди. Ако ви трябва повече време, отговорете веднага и докладвайте резултата по-късно през обратното извикване.
  • Размер на отговора. Skava чете максимум 256 KiB.
  • 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: обратният извик за това конкретно взаимодействие, вижте по-долу. Те присъстват само когато извикването идва от чат.

Контекстни полета като име, фирма, проект или подчат се попълват от самия сървър, изведени от канала, в който е изпълнен елементът. Клиент, който е манипулиран, не може да твърди друго име на проекта там.

Отговорът: форматът на картата

Отговорете с 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 или entity водят до отхвърляне; файлът може да бъде най-много 8 KiB и да съдържа най-много 16 форми. Цветът, дебелината на контура и размерът се задават от Skava, така че иконата не може да се маскира като контрол. Работете с мрежа 24 на 24.

Без icon остава стандартният маркер.

Обратното извикване: докладване на по-късни състояния

Извикването съдържа callback_url и callback_token. Използвайте ги, за да докладвате нови състояния по-късно:

POST <callback_url> с Authorization: Bearer <callback_token> и Content-Type: application/json, тяло до 32 KiB:

{"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 интерфейси. Попълними документи вместо интерфейси: Персонализирани елементи: Документи.