Собствени елементи: API

API интерфейс е форма, чиито попълнени стойности Skava изпраща като JSON до адрес, който вие посочвате (ваш бекенд). По този начин можете да свържете Skava сигурно със собствените си системи.

Настройте 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 го добавя от страна на сървъра към конфигурирания заглавок. Ако зададете дата на изтичане, Skava отказва извикването след изтичането и ви моли да подновите токена.

Тестване: Ping и Тестово искане

• Пинг : лека проверка за достъпност. Тя проверява само дали вашият адрес отговаря и не изпраща токен или данни от форма по време на процеса. Показва достъпност, статус и време за отговор. Идеален като първа стъпка.
• Тестово искане : истинското изпитателно изпълнение: изпраща примерни данни, включително токен до вашия адрес и ви показва пълния отговор, както и извлечените полета за отговор.

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

Чернова и Публикуване

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

Сигурност

Как екипът използва публикуван интерфейс

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

1. В чата докоснете Плюс в долната част и изберете Персонализиран елемент.
2. Изберете желания шаблон или интерфейс от списъка.
3. Попълнете формуляра и натиснете Изпращане.
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.

Свързано

Искате ли вместо това да създадете попълним шаблон на документ? Вижте Custom Elements: Documents.

Често задавани въпроси