Skava Skava / Wiki

Ова страница је намењена програмерима који повезују позадински систем компаније са Skava. На страници Прилагодљиви елементи: интерфејси API-ја објашњено је како се ствара и објављује API елемент; овде покривамо све што мора да се догоди на другој страни везе.

Идеја у једној реченици: Skava не познаје вашу делатност. Зна само један формат, картицу. Ви одлучујете шта пише на њој, ми само проверавамо облик, величину и безбедност. Наручивање материјала је један пример; следећа компанија сакупља повратне информације корисника, а наредна архивира фотографију градилишта у својим евиденцијама.

Преглед процеса

  1. Администратор компаније ствара API елемент у Skava: формулу, адресу вашег позадинског система, методу и токен.
  2. Неко у чату попуњава форму и шаље је.
  3. Skava poziva vaš backend i šalje popunjene vrednosti kao JSON.
  4. Vaš odgovor postaje karta u četu.
  5. Opciono, kasnije možete prijaviti nova stanja putem callback. Svako prijavljivanje postaje nova karta; prethodna ostaje.

Zahtevi za vaš backend

  • HTTPS. Samo https://, bez http, bez poverljivih podataka u adresi, najviše 2000 karaktera.
  • Доступно јавно. Хост мора да се резолвира искључиво на јавне ИП адресе. Локалхост, приватне мреже, линк-локал и облак метаданци су одбијени, а то се проверава при сваком позиву.
  • Фиксна адреса. Скава резолвира хост једном и везује везу на ту ИП адресу. Промена ДНС-а током позива нема ефекта.
  • Без прусмеравања. Пренос 301 на „тачну" адресу сматра се неуспехом. Унесите коначну адресу одмах.
  • Време одговора. Време истекла је конфигурисано по елементу и тврдо ограничено на 30 секунди. Ако вам треба дуже, одговорите одмах и пријавите резултат касније преко повратног позива.
  • Величина одговора. Скава чита највише 256 КиБ.
  • Content-Type. Tijelo se analizira samo uz application/json.

Zahtev koji stiže do vas

Metoda je GET, POST, PUT ili PATCH, u zavisnosti od elementa. Kod POST, PUT i PATCH vrednosti stižu kao JSON tijelo, dok kod GET dolaze kao parametri upita.

Autentifikacija je jedna zaglavlja čije ime i prefiks vrednosti su konfigurisani u elementu, obično Authorization sa prefiksom Bearer . Token je šifrovan na našoj strani. Zaglavlja host, content-length, content-type, cookie i accept-encoding ne mogu biti postavljena.

Tijelo je ravni objekat. Ključeve bira onaj ko je napravio element; ugniježđivanje se pojavljuje samo tamo gde su dodali tabelu ili biralicu proizvoda:

{"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": "…"}

Tri ključa uvek dolaze od nas, pa ih nemojte koristiti sami:

  • locale: jezički kod korisnika. Odgovorite na tom jeziku; mi ne prevodimo vaše tekstove.
  • callback_url i callback_token: povratni poziv za ovu interakciju, vidite u nastavku. Prisutni su samo kada poziv dolazi iz chata.

Polja konteksta poput imena, firme, projekta ili podrazgovora popunjava sam server, izvedena iz kanala u kojem je element pokrenut. Izmenjeni klijent ne može tamo tvrditi drugo ime projekta.

Odgovor: format kartice

Odgovorite sa 2xx i objektom card. To je tačno ono što postaje kartica u četu:

{"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 (obavezno): ceo broj 1. Kao tekst ("1") odbija se. Bez njega odgovor se ne računa kao kartica i primenjuje se mapiranje odgovora konfigurisano u elementu.
  • title: naslov kartice.
  • state: samo boja i ton ikone, jedna od vrednosti ok, pending, warn, error. Nepoznata vrednost vraća se na ok i dobijate uputstvo.
  • status_text: slobodan tekst koji ne tumačimo. Nalazi se na vrhu kartice i to je ono što se prikazuje u listi četa i u obaveštenju.
  • fields: lista label i value. Najviše 20 stavki, label 80 znakova, value 200, title i status_text po 120. Preduge vrednosti se skraćuju, a ne odbacuju: porudžbina ne sme da propadne zbog detalja.
  • icon: vidi ispod.

Šta Skava radi sa vašim tekstovima pre nego što stignu u chat: uklanjaju se prelazi linije i kontrolni znaci (znak za pisanje s desna na levo bi inače mogao da obrne prikaz iznosa), zamenjuju se obrnuti navodnici, a sve što počinje sa [SKAVA: se neutrališe. Poslednje sprečava da se vrednost kartice protumači kao drugi element chata, na primer zahtev za plaćanje.

Linkovi u poljima, HTML i slike se ne mogu postaviti. Chat je okruženje poverenja, a klikabilna adresa sa stranog backend-a bila bi poziv za ponovno izgradnju stranice za prijavu.

Ulazi korisnika pripadaju serveru: pojavljuju se na prvoj kartici i ne možete ih prebrisati. U chatu oni predstavljaju zapis onoga što je zapravo poslato.

Ikone

Kartica dobija svoj znak u zaglavlju pomoću icon. Dva načina:

Ime iz priloženog seta: 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.

Ili vaš sopstveni SVG kao niz. Skava iz njega uzima samo geometriju (path, circle, ellipse, rect, line, polyline, polygon sa njihovim numeričkim atributima) i gradi sopstvenu sliku. Skripte, stilovi, spoljne reference, foreignObject i atributi događaja se odbacuju; doctype ili entitet dovodi do odbijanja; fajl može biti najviše 8 KiB i sadržati najviše 16 oblika. Boju, debljinu linije i veličinu postavlja Skava, pa ikonica ne može da se prikači kao kontrola. Radite na mreži 24 x 24.

Bez icon ostaje podrazumevani znak.

Povratni poziv: prijavljivanje kasnijih stanja

Poziv sadrži callback_url i callback_token. Koristite ih za kasnije prijavljivanje novih stanja:

POST <callback_url> sa Authorization: Bearer <callback_token> i Content-Type: application/json, telo najviše 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}

Pored kartice postoje tri opcione vrednosti:

  • seq: vaš sopstveni brojilac. Izveštaj sa manjom ili jednakom vrednošću se odbacuje, tako da dva izveštaja ne mogu da se pretiču. Bez seq pobeduje poslednji koji stigne.
  • final: završava interakciju. Token postaje nevažeći i više se ne pojavljuju nove kartice. Dozvoljeno je i u prvom odgovoru za tokove bez nastavka.
  • notify: postavite na false da se kartica objavi tiho, bez broja nepročitanih poruka i bez obaveštenja. Koristite za međukorake koji ne bi trebalo da probude nikoga. Bez ove opcije, kartica je potpuno normalna poruka.

Svako izveštavanje postaje svoja kartica u četu, a prethodna ostaje. Tako je jasno koje stanje je prijavljeno. Iz toga proizilazi preporuka: šaljite samo ono što se promenilo. Kartica koja četvrti put ponavlja broj narudžbine, stavke i ukupan iznos samo je šum za čitaoca.

Dva ograničenja: isti izveštaj poslat dva puta ne stvara drugu karticu, a interakcija može objaviti najviše 50 kartica. Interakcija prihvata izveštaje tokom 90 dana.

Odgovori na koje treba da reagujete

  • 200 uz {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Pročitajte upute: one kažu šta je skraćeno ili izbačeno.
  • 401: netačan token ili ID interakcije. Ne pokušavajte ponovo.
  • 410: interakcija zatvorena ili istekla. Ne pokušavajte ponovo.
  • 422: kartica neupotrebljiva, uz hints kao razlog. Prvo je ispravite.
  • 400 neispravan JSON, 413 preveliko, 429 previše zahteva (ponovite sa pauzom), 500 naša greška, pokušajte kasnije.

Primer 1: porudžbina sa istorijom statusa

Korak 1, zahtev ka vašem backend-u:

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"}

Korak 2, vaš trenutni odgovor:

{"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"}]}}

Čet sada prikazuje karticu sa ikonicom paketa, statusom i unosima korisnika.

Korak 3, kasnije tokom pakovanja:

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

Tiha druga kartica bez polja: promenio se samo status.

Korak 4, pri slanju:

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}

Ova kartica može probuditi nekoga, zato nema notify: false.

Korak 5, pri isporuci:

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

Sa final interakcija je zatvorena i token više ne funkcioniše.

Пример 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 дана са важећим токеном, иако ви никада више нећете пријављивати ништа.

Изборник производа из каталога

Када компанија унесе свој каталог артикула, елемент може да садржи блок изборника производа. Корисник саставља корпу, а ви је примајте као листу под кључем који је одabraо онај ко је изградио елемент:

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

Пошто је кључ бесплатан, потражите прву листу која има овај облик, а не фиксно име. Пре слања, Skava проверава да ли сваки број заиста постоји у каталогу те компаније, највише 50 ставки. У картици ставке се приказују као листа са сликом производа, именом и количином.

Тестирање

  • Пинг у уређивачу елемента шаље гол HEAD захтев без токена и без података. Одговорите било чим; било који HTTP одговор се броји као достижан.
  • Тест захтев покрене прави позив са примерима вредности, чак и док је елемент и даље нацрт, и приказује захтев, одговор и поруке валидатора картице.
  • Преглед у следећем језику: залепите свој одговор у JSON формату, проверите и видећете завршену картицу са упутствима. Проверава се на серверу истим кодом као у продукцији.
  • Пример сервера: потпуно функционалан пример добављача ради на api.skava.io и користи све што је описано изнад. Његов изворни код се налази у репозиторијуму у example_order_server/, око 600 линија чисте стандардне библиотеке, намењено за копирање.

Шта још треба да знате

  • Картица је савршено обична порука у чату. Појављује се у претрази, може се навести и остаје у историји.
  • Пошаље је системски слаоц, а не налог ваше компаније. Ипак, појављује се на страни оне особе која је покренула елемент, а у наслову је наведено чији систем пише.
  • Ко може да га покрене поставља се на елементу: само чланови компаније или такође и спољни корисници који деле чат са њим. Када ваша компанија напусти чат, дозвола се сама укида.
  • API element sa isteklim tokenom je neaktivan i ne pojavljuje se u meniju dok administrator ne sačuva novi.

Povezano

Kreiranje i objavljivanje: Prilagođeni elementi: API interfejsi. Popunljivi dokumenti umesto interfejsa: Prilagođeni elementi: Dokumenti.