Skava Skava / Wiki

Ez az oldal azoknak a fejlesztőknek szól, akik egy vállalat háttérendszereit Skavához kapcsolják. Az API-elem létrehozásának és kiadásának módját a Egyedi elemek: API-felületek oldalon tárgyaljuk; itt mindent lefedünk, ami a vonal másik végén történik.

Az ötlet egy mondatban: Skava nem ismeri a saját szakterületét. Pontosan egy formátumot ismer: a kártyát. Ön dönti el, mi áll rajta; mi csak az alakot, a méretet és a biztonságot ellenőrizzük. Egy anyagmegrendelés például ilyen; a következő cég felhasználói visszajelzéseket gyűjt, az azt követő pedig saját nyilvántartásába rögzít egy helyszíni fotót.

A folyamat áttekintése

  1. Egy vállalati adminisztrátor létrehoz egy API-elemet Skavában: egy űrlapot, valamint a háttérendszere címét, módszerét és tokenjét.
  2. Valaki a csevegésben kitölti az űrlapot és elküldi.
  3. A Skava hívja a backendet, és JSON formátumban küldi a kitöltött értékeket.
  4. A válasz a kártya lesz a csevegésben.
  5. Opcionálisan később új állapotokat is jelenthet a visszahívás (callback) segítségével. Minden jelentés egy új kártyát hoz létre; a korábbi megmarad.

A backendre vonatkozó követelmények

  • HTTPS. Kizárólag https://, nincs http, nincs hitelesítő adat a címben, maximum 2000 karakter.
  • Közös elérhetőség. A host kizárólag nyilvános IP-címekre mutathat. A localhost, a magánhálózatok, a link-local címek és a felhő metaadatok elutasításra kerülnek, ezt minden hívásnál ellenőrizzük.
  • Rögzített cím. A Skava a hostot egyszer feloldja, és a kapcsolatot ehhez az IP-címhez rögzíti. A hívás közbeni DNS-változásnak nincs hatása.
  • Nincs átirányítás. A „helyes” címre mutató 301-es átirányítás hiba. Adja meg azonnal a végső címet.
  • Válaszidő. Az időtúllépés határértéke elemenként konfigurálható, de legfeljebb 30 másodperc. Ha hosszabb időre van szüksége, azonnal válaszoljon, és a callback-en keresztül később jelentse az eredményt.
  • Válasz mérete. A Skava legfeljebb 256 KiB-ot olvas be.
  • Content-Type. A test csak application/json formátumban értelmezhető.

A hozzád érkező kérés

A módszer GET, POST, PUT vagy PATCH, az elem típusától függően. A POST, PUT és PATCH esetén az értékek JSON testként érkeznek, a GET esetén pedig lekérdezési paraméterként.

Az hitelesítés egy olyan fejléc, amelynek neve és értékének előtagja az elemben van beállítva, általában Authorization a Bearer előtaggal. A token titkosítva tárolódik a mi oldalunkon. A host, content-length, content-type, cookie és accept-encoding fejlécek nem állíthatók be.

A test egy lapos objektum. A kulcsokat az elem fejlesztője választja; a hierarchia csak akkor jelenik meg, ha táblázatot vagy termékválasztót adtak hozzá:

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

Három kulcs mindig tőlünk érkezik, ezért ne használja őket saját maga:

  • locale: a felhasználó nyelvkódja. Válaszoljon ezen a nyelven; mi nem fordítjuk a szövegeit.
  • callback_url és callback_token: a visszahívás az adott interakcióhoz, lásd lentebb. Ezek csak akkor jelennek meg, ha a hívás egy csevegésből indul.

A kontextusmezők, mint például név, cég, projekt vagy albeszélgetés, a szerver tölti ki automatikusan, a csatorna alapján, amelyben az elem futott. Egy módosított kliens nem tud itt más projektnevet feltüntetni.

A válasz: a kártya formátuma

Válaszoljon 2xx kóddal és egy card objektummal. Ez lesz pontosan a csevegésben megjelenő kártya:

{"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 (kötelező): a 1 egész szám. Szövegként ("1") elutasítjuk. Ha hiányzik, a válasz nem számít kártyának, és az elemre beállított válaszleképezés lép életbe.
  • title: a kártya címe.
  • state: csak a szín és az ikontónus, az alábbiak egyike: ok, pending, warn, error. Ismeretlen érték esetén az ok lép életbe, és egy utasítást kap.
  • status_text: szabad szöveg, amelyet nem értelmezünk. A kártya tetején jelenik meg, és ez látható a csevegéslistában és az értesítésben is.
  • fields: egy label és value listája. Legfeljebb 20 bejegyzés, label 80 karakter, value 200, title és status_text mindegyik 120 karakter. A túl hosszú értékeket rövidítjük, nem utasítjuk el: egy megrendelés nem csúszhat meg egy részlet miatt.
  • icon: lásd lentebb.

Mit csinál a Skava a szövegeiddel, mielőtt azok eljutnának a csevegésbe: a sortöréseket és vezérlőkaraktereket eltávolítjuk (egy jobbról balra írású karakter különben megfordíthatná egy összeg megjelenését), a backtick-eket helyettesítjük, és minden [SKAVA:-rel kezdődő elemet semlegesítünk. Az utóbbi megakadályozza, hogy egy kártyaértéket más csevegési elemként olvassanak fel, például fizetési kérésként.

A mezőkben, HTML-ben és képeken linkek nem állíthatók be. A csevegés egy megbízható környezet, és egy idegen háttérendszerről származó kattintható cím a bejelentkezési oldal újjáépítésének csábítása lenne.

A felhasználó beviteli adatai a szerver tulajdonát képezik: az első kártyán jelennek meg, és nem írhatod felül őket. A csevegésben ezek a ténylegesen benyújtott adatok nyilvántartását képezik.

Ikonok

A icon elemmel a kártya saját jelzést kap a fejlécben. Két lehetőség:

Egy név a beépített készletből: 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.

Vagy saját SVG szöveges formában. Ebből a Skava csak a geometriát veszi át (path, circle, ellipse, rect, line, polyline, polygon a numerikus attribútumaikkal), és ebből építi fel a saját képét. A scriptek, stílusok, külső hivatkozások, foreignObject és eseményattribútumok elvetésre kerülnek; a doctype vagy entitás elutasításhoz vezet; a fájl mérete legfeljebb 8 KiB lehet, és legfeljebb 16 alakzatot tartalmazhat. A színt, vonastagságot és méretet a Skava állítja be, így egy ikon nem adhatja ki magát vezérlőelemnek. 24x24-es rácsban dolgozzon.

icon nélkül a alapértelmezett jelzés marad.

A visszahívás: későbbi állapotok jelentése

A hívás tartalmazza a callback_url és a callback_token értékeket. Használja őket a későbbi új állapotok jelentéséhez:

POST <callback_url> a Authorization: Bearer <callback_token> és a Content-Type: application/json fejléccel, a test legfeljebb 32 KiB méretű:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

A kártyán kívül három opcionális érték is létezik:

  • seq: saját számlálója. Egy kisebb vagy egyenlő értékű jelentést elvetnek, így két jelentés nem előzheti meg egymást. seq nélkül az utolsó megérkező jelentés a nyerő.
  • final: lezárja a kölcsönhatást. A token érvénytelenné válik, és további kártyák nem jelennek meg. A first válaszban is megengedett, ha a folyamatnak nincs folytatása.
  • notify: false értékre állítva a kártya csendesen kerül közzétételre, olvasatlan számláló és értesítés nélkül. Ez a lépések középső szakaszaira alkalmas, amelyek nem ébresztik a felhasználókat. Ha ez elmarad, a kártya egy teljesen normális üzenetként jelenik meg.

Minden jelentés a csevegésben saját kártyává válik, a korábbiak pedig megmaradnak. Így egyértelmű, hogy mely állapotot jelentették be. Ebből következik az alábbi javaslat: csak a megváltozottakat küldje el. Egy kártya, amely negyedszer ismétli meg a rendelés számát, a tételeket és az összeget, csak zajt okoz az olvasónak.

Két korlát: ugyanaz a jelentés kétszer nem hoz létre második kártyát, és egy kölcsönhatás legfeljebb 50 kártyát tehet közzé. Egy kölcsönhatás 90 napig fogad el jelentéseket.

Olyan válaszok, amelyekre reagálnia kell

  • 200 és {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Olvassa el a tippeket: ezek jelzik, mi lett lerövidítve vagy elhagyva.
  • 401: hibás token vagy interakciós azonosító. Ne próbálja újra.
  • 410: az interakció lezárva vagy lejárt. Ne próbálja újra.
  • 422: a kártya használhatatlan, az ok a hints mezőben található. Először javítsa ki.
  • 400 sérült JSON, 413 túl nagy, 429 túl sok kérés (újrapróbálkozás növekvő várakozással), 500 a mi hibánk, próbálja meg később.

1. példa: rendelés státusz-történettel

1. lépés, a kérés a backend felé:

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. lépés, a gyors válasz:

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

A csevegés most egy csomag ikonnal, a státusszal és a felhasználó adataival ellátott kártyát mutat.

3. lépés, később a szedés során:

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

Egy csendes második kártya, mezők nélkül: csak az állapot változott.

4. lépés, a szállításnál:

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}

Ez a kártya felébresztheti valakit, ezért nincs notify: false.

5. lépés, a kézbesítésnél:

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

A final beállítással a interakció lezárul, és a token már nem működik.

2. példa: egy utókövetést nem igénylő művelet

Nem minden folyamat rendelkezik előzménnyel. Egy olyan elem, amely egyetlen mezővel rendelkezik és valamit átad a rendszerének, csak egy választ igényel:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

A final: true itt a lényeg: különben a kölcsönhatás 90 napig nyitva maradna egy érvényes token mellett, még akkor is, ha soha többé nem jelentkezik semmi.

Termékválasztó a katalógusból

Miután a vállalat feltöltötte a cikk-katalógusát, az elem tartalmazhatja a termékválasztó blokkot. A felhasználó ebből állítja össze a kosarat, amelyet Ön a listaként kap meg az elem létrehozója által választott kulcs alatt:

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

Mivel a kulcs szabadon megadható, nem egy rögzített név, hanem az első, ennek megfelelő alakú listát keresse. Küldés előtt a Skava ellenőrzi, hogy minden szám tényleg létezik-e az adott cég katalógusában, legfeljebb 50 tétel esetén. A kártyán a tételek termékfotóval, névvel és mennyiséggel ellátott listaként jelennek meg.

Tesztelés

  • Az elem szerkesztőjében a Ping egy token nélküli és adat nélküli, csupán HEAD kérést küld. Bármilyen választ adjon; bármilyen HTTP-válasz elérhetőnek minősül.
  • A Kérés tesztelése egy valós hívást indít mintaértékekkel, még akkor is, ha az elem még tervezet, és megjeleníti a kérést, a választ, valamint a kártya érvényesítőjének üzeneteit.
  • A mellette lévő fülön található Előnézet: illessze be a válasz JSON-t, ellenőrizze, és látni fogja a kész kártyát a tippekkel együtt. A szerveren ugyanazzal a kóddal ellenőrzi, mint éles környezetben.
  • Példa szerver: egy teljes körű példa szolgáltató fut a api.skava.io címen, és mindent használ, amit fent leírtunk. Forráskódja a example_order_server/ könyvtárban található a tárolóban, kb. 600 sor tiszta szabványos könyvtár, amelyet másolni lehet.

Mire még érdemes figyelni

  • A kártya egy teljesen rendes chat üzenet. Megjelenik a keresésben, idézhető, és megmarad az előzményekben.
  • A rendszer küldi, nem a céged fiókjából. Mégis az illető oldalán jelenik meg, aki futtatta az elemet, és a címében szerepel, melyik rendszer írta.
  • Az elemen beállítva van, hogy ki futtathatja: csak a cég tagjai, vagy külsősök is, akik megosztják a chatet vele. Ha a céged kilép a chatből, a jogosultság magától megszűnik.
  • A lejárt tokennal rendelkező API-elem inaktív, és nem jelenik meg a menüben sem, amíg egy rendszergazda nem tárol egy újat.

Kapcsolódó

Létrehozás és kiadás: Egyedi elemek: API-felületek. Kitölthető dokumentumok a felületek helyett: Egyedi elemek: Dokumentumok.