Персонализирани елементи: API

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

Настройка на API интерфейс

Интерфейсът се състои от полета за въвеждане (те формират JSON), целев адрес и автентикация.

1. Създаване на полета: Всяко поле получава JSON ключ. Вдясно виждате JSON преглед в реално време, който се изпраща към вашия backend точно по този начин.
2. Адрес (URL): адресът https:// на вашия backend. Допускани са само HTTPS и публично достъпни адреси (вижте „Сигурност“ по-долу).
3. Метод: POST (по подразбиране), PUT, PATCH или GET. При GET стойностите се добавят като query параметри вместо да се изпращат в тялото.
4. Автентикация: Задайте името на заглавката (напр. Authorization) и префикса на стойността (напр. Bearer ), след което запазете токена. По желание задайте срок на валидност.
5. Полета в отговора (по избор): Определете по път кои стойности от отговора на backend-а да се показват: напр. order.id или items[0].sku.
6. Проверете с Ping и Test Request, след което натиснете Release.

Съхранявайте токена безопасно

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

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

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

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

Създаване и публикуване

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

Сигурност

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

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

1. В чата докоснете Плюс в долната част и изберете желания елемент, например Поръчка на материали.
2. Попълнете формата и натиснете Изпрати.
3. Резултатът се появява като карта в чата и е видим за всички участници в разговора.

Нека ИИ изгради елемент

Като администратор на компанията не е нужно да използвате редактора сами. Кажете на 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: Документи.

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