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

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

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

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

Изисквания към вашия бекенд

• 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: свободен текст, който ние не интерпретираме. Той се намира в горната част на картата и също така се показва в списъка с чатове и в push известията.
• 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 и атрибути за събития се отхвърлят; доктип или сущност води до отхвърляне; файлът може да бъде най-много 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: приключва взаимодействието. Токенът става невалиден и повече карти не се показват. Разрешено е и в first отговор за потоци без последващи стъпки.
• notify: задайте false, за да публикувате картата тихо, без брой непрочетени и без известие. За междинни стъпки, които не трябва да будят никого. Без това картата е напълно нормално съобщение.

Всеки доклад става своя собствена карта в чата, предишната остава. По този начин е ясно кое състояние е докладвано. От това следва препоръка: пращайте само промененото. Карта, която повтаря номер на поръчка, артикули и обща сума за четвърти път, е просто шум за читателя.

Две ограничения: същият доклад два пъти не създава втора карта, а едно взаимодействие може да публикува най-много 50 карти. Едно взаимодействие приема доклади в продължение на 90 дни.

Отговори, на които трябва да реагирате

• 200 с {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Прочетете подсказките: те казват какво е съкратено или изпуснато.
• 401: грешен токен или ID на взаимодействие. Не се опитвайте отново.
• 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 интерфейси. Запълваеми документи вместо интерфейси: Потребителски елементи: Документи.