Skava Skava / Wiki

Egyedi elemek: API

Az API-felület egy űrlap, amelynek kitöltött értékeit a Skava JSON formátumban küldi egy általad megadott címre (a te háttérszolgáltatásodra). Így csatlakoztathatod biztonságosan a Skavát a saját rendszereidhez.

i

Az API-felületeket a Webappban, a Egyedi elemek menüpont alatt kezeld, és kapcsolod be az API-felületek kapcsolót. A létrehozás és szerkesztés a vállalati adminisztrátorok feladata; a kiadott felületeket a vállalat minden tagja használhatja.

API-felület beállítása

Egy felület beviteli mezőkből (amelyek alkotják a JSON-t), a célcímből és a hitelesítésből áll.

  1. Mező létrehozása: Minden mezőhöz rendeljen egy JSON kulcsot. Jobbra élőben látható a JSON előnézet, amely pontosan ebben a formában kerül továbbításra a backend felé.
  2. Cím (URL): a backend https:// címe. Csak HTTPS-es és nyilvánosan elérhető címek megengedettek (lásd az Alábbi biztonsági részt).
  3. Módszer: POST (alapértelmezett), PUT, PATCH vagy GET. A GET használata esetén az értékek lekérdezési paraméterként csatolódnak, nem a testben.
  4. Hitelesítés: Adja meg a fejléc nevét (pl. Authorization) és az érték előtagját (pl. Bearer ), majd mentse a jelvényt. Opcionálisan állíthat be lejárati dátumot is.
  5. Válasz mezők (opcionális): Útvonal alapján határozza meg, hogy a backend válaszában mely értékek jelenjenek meg: pl. order.id vagy items[0].sku.
  6. Ellenőrizd a Ping és a Test Request funkcióval, majd kattints a Release gombra.
Skava webapp: Az API interfész Mezők fül. Fent az automatikusan tartalmazott kontextusértékek (felhasználónév, cég, projekt …), alul a egyedi mezők JSON kulccsal, jobbra az űrlap előnézet és az élő JSON előnézet.
A Mezők fül: minden mezőhöz tartozik egy JSON kulcs. Fent a felhasználó, cég és projekt nevét jelölő kontextusértékek automatikusan szerepelnek. Jobbra az űrlap és a JSON élő : pontosan ez kerül továbbításra a backend felé.
Skava webapp: Az API interfész Endpoint fül, amelyben a URL, a POST metódus, a időkorlát, az auth fejléc, a Bearer érték előtag és a titkosított token beviteli mezője található.
Az Endpoint fül: célcím (csak HTTPS), metódus, időkorlát, valamint auth fejléc és érték előtag. A token titkosítva tárolódik, és soha nem kerül átadásra a klienseknek.
Skava webapp: API felület Előnézet fül. A válaszban be van állítva a Success JSON kulcs, jobbra pedig az előnézet mutatja, hogyan fog kinézni az eredmény a csevegésben.
A Előnézet fül (opcionális): útvonal alapján határozd meg, hogy a backend válasz mely értékei jelenjenek meg. Jobbra a Skava ezekből építi fel az eredménykártyát, pontosan úgy, ahogy az később a csevegésben is megjelenik.

Token biztonságos tárolása

A token titkosítva tárolódik, és soha nem kerül vissza az ügyfelekhez: az alkalmazás csak azt mutatja, hogy van-e beállítva token, és mikor jár le. Küldéskor a Skava szerveroldalon csatolja a beállított fejléchez. Ha beállítasz lejárati dátumot, a Skava a lejárás után elutasítja a hívást, és arra kéri, hogy megújítsd a tokent.

Tesztelés: Ping és Teszt kérés

  • Ping: egy könnyű elérhetőségi ellenőrzés. Csak azt nézi meg, hogy válaszol-e a címed, közben nem küld token vagy űrlapadatokat. Megjeleníti az elérhetőséget, az állapotot és a válaszidőt. Ideális első lépésnek.
  • Próbakérés: a valódi próba: mintaadatokat, token is küld a címedre, és megmutatja a teljes választ, valamint a kinyert válaszmezőket.

Adminisztrátorként mindkettőt futtathatod vázlat módban is, hogy a kiadás előtt ellenőrizd az integrációt.

Skava webapp: egy API-felület Teszt fülje a Ping és a Próbakérés gombokkal, a 200 OK állapotkóddal, a válaszidővel és a backend teljes JSON-válaszával.
A Teszt fül: a Ping és a Próbakérés egymás mellett. Itt 200-as állapottal, válaszidővel és a backend teljes JSON-válaszával.

Piszkozat és kiadás

Minden interfész piszkozatként indul, és szabadon szerkeszthető. Amikor minden kész, a Kiadás gombbal teszed élesbe.

!

A kiadás után a célcím, a metódus, a mezők, a hitelesítési fejléc és az időkorlát rögzül. Ez szándékos: senki ne tudjon csendben átirányítani, ahová az adatok mennek. Pontosan három dolog marad módosítható, mert a működtetéshez szükségesek: a token és a lejárat (így cserélhető ki az lejárt vagy használt token), valamint a közönség, azaz hogy csak a saját csapat, vagy partnercégek is indíthatják-e a chatben. Minden más változtatáshoz új verziót kell létrehozni.

Biztonság

i

Az interfész visszaélés elleni védelmére szigorú szabályok vonatkoznak: csak HTTPS címei engedélyezettek, és a címnak nyilvános célcímre kell mutatnia: a belső címei (pl. localhost, privát hálózatok, vagy felhőfémadatok) elutasítva. A Skava minden hívásnál ellenőrzi ezt, pontosan a hitelesített címhez kapcsolódik, nem követi az átirányításokat, és korlátozza az időtúllépést és a válasz méretét.

Hogyan használja a kiadott felületet a csapat

Amint egy felület kiadva lett, a cég minden tagja közvetlenül a csevegésből indíthatja, szerkesztő nélkül. Nincs közös beviteli mező és nincs közbeeső párbeszédablak: minden kiadott elem a plusz menüben jelenik meg a saját nevén, a kínáló cég logójával.

  1. A csevegésben érintse meg az alján a Plusz gombot, majd azt az elemet, amit szeretne, például a Anyagrendelés opciót.
  2. Töltse ki az űrlapot, és kattintson a Küldés gombra.
  3. Az eredmény kártyaként jelenik meg a csevegésben, mindenki számára láthatóan a beszélgetésben.
Skava webapp: kitöltendő űrlap a Material order API-művelethez, amelynek mezői: cikkszám, leírás, mennyiség, mértékegység, kért szállítási dátum és megjegyzés, valamint a megjegyzés a automatikusan tartalmazott értékekről.
3. lépés: töltsd ki az űrlapot. Az alján lévő megjegyzés megmutatja, melyik értékek kerülnek automatikusan be.
Skava webapp: eredménykártya a Material order API-művelethez a csevegésben, 200-as státusszal, a megadott értékekkel, valamint a backend-válasz (rendelésszám, státusz, szállítási dátum) és a kibontható nyers adatokkal.
4. lépés: az eredménykártya a csevegésben, a bemeneti adatokkal és a backend-válaszoddal.

Engedd, hogy az AI építsen elemet

Cégtulajdonosként nem kell magadnak használnod a szerkesztőt. Mondd el a Skava asszisztensnek a csevegésben, például: „Készíts egy rendelési űrlapot a katalógusomhoz, mennyiséggel és szállítási címmel”. Ebből készít egy vázlatot, később mezőről mezőre módosíthatod, és ismeri a feltöltött cikkkatalógusodat: rendelésnél a termékválasztót javasolja, nem pedig szöveges mezőt a cikkszámhoz.

Ezt is beállíthatja: a végpontot és a metódust, valamint a célközönséget („csak cégtársak” vagy „külsősök is, ha ugyanabban a csevegésben vannak”). A célközönségnél először megkérdezi, ahelyett hogy egyszerűen beállítaná, mert ez dönti el, ki futtathat valamit kívülről.

Amit kifejezetten nem érint: a hozzáférési tokent. Soha nem kér, és soha nem fogad el ilyet, mert a csevegési üzenetek tárolva vannak. Te írod be a szerkesztőben, egyébként nem indul ki hívás. És nem tud közzétenni: az utolsó lépés nálad marad, így semmi nem lesz látható a ügyfelek számára ellenőrzés nélkül.

Ki futtathatja

Az „Endpoint” fül azt mondja meg, ki használhat egy elemet. Az alapértelmezés a céged tagjai. A második beállítás megnyitja a hozzáférést a külsősök előtt, de csak olyan csevegésben, ahol a céged egy tagja is jelen van: pontosan az az eset, amire tervezve van, amikor az ügyfél rendel tőled. Amikor a céged kilép a csevegésből, a jogosultság magától megszűnik.

Termékek a saját katalógusodból

Amint feltöltötted a cikkkatalógusod, az építő felületen megjelenik a termékválasztó blokk. Nincs mit karbantartani: a lista a te katalógusod. A rendelő személy keres benne, látja a képet, a nevet és a cikkszámot, a te backended pedig megkapja a cikkszámot. A Skava elutasítja azt a számot, amely nincs a katalógusodban. A mennyiséghez tegyél mellé egy sima számmező.

A kártyát te határozod meg

A te backended dönti el, mit ír a kártya. A Skava csak az alakot, a méretet és a biztonságot ellenőrzi, soha nem az értelmet: nem ismeri a rendelési állapotokat, sem a mezőneveket. Ehhez válaszolj egy card objektummal:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

  • Az v értékének 1 egész számnak kell lennie. Ha nincs meg, a válasz nem számít kártyának, és az elembe beállított válaszleképezés lép életbe.
  • A(z) state csak színt és ikont jelent: ok, pending, warn vagy error. Minden, ami tartalmat hordoz, szabad szövegként kerül a(z) status_text mezőbe.
  • A(z) fields egy címkék és értékek listája, legfeljebb 20 bejegyzéssel. A túl hosszú értékeket nem utasítják el, hanem lerövidítik, így egy rendelés sosem bukik el apró részletek miatt.

A felhasználói bevitel a szerverhez tartozik: a backend küldött adatától függetlenül érintetlen marad. Ez a chatben rögzített bizonyíték arról, mi lett ténylegesen beküldve.

Állapotjelentés később

Amikor az elem fut, a Skava két extra értéket küld: callback_url és callback_token. Ide jelentheted be később az új állapotot, és egy új kártya jelenik meg a chatben, a telefonon is, miközben valaki nézi. Az előző kártya megmarad, így olvasható, melyik állapotot jelentették be. Küldd ugyanazt a(z) card objektumot, mint fent, POST kéréssel, a(z) Authorization: Bearer <callback_token> fejléccel. Három opcionális érték kerül a kártya mellé:

  • seq: a saját számlálód. A kisebb vagy egyenlő értékű jelentés elvetésre kerül, így két jelentés nem előzheti meg egymást.
  • final: lezárja a interakciót. A token érvényét veszti, és a kártya végleges lesz.
  • notify: állítsd false értékre, ha a kártyát csendben szeretnéd közzétenni, olvasatlan számláló és értesítés nélkül. Köztes lépésekhez, amelyek nem ébresztik senkit. Ha nincs meg, a kártya egy teljesen normális üzenet.

Egy interakció legfeljebb 50 kártyát közzétehet. Ha ugyanazt a jelentést kétszer küldöd, az nem eredményez második kártyát.

A Skava 200 kóddal és egy hints listával válaszol, ha valamit lerövidítettek vagy eldobtak, és 422 kóddal, ha a kártya használhatatlan volt. Egy interakció 90 napig fogad jelentéseket.

A kártyákat a Skava rendszerküldője teszi közzé, nem az a személy, aki futtatta az elemet, és nem is a saját céged fiókja. A kártya címében szerepel, melyik rendszer írja.

Egy teljes, másolható példa található a tárolóban a example_order_server/ alatt, és fut a api.skava.io címen.

Kapcsolódó

Szeretnél inkább kitölthető dokumentumsablonokat készíteni? Lásd: Egyedi elemek: Dokumentumok.

Gyakori kérdések

Mi az API felület a Skavában?

Olyan űrlap, amelynek kitöltött értékeit a Skava JSON formátumban küldi egy általad megadott címre (a te háttérszolgáltatásodra): kényelmes a Skava saját rendszereiddel való összekötéséhez.

Ki hozhat létre és indíthat API felületeket?

A létrehozás és szerkesztés a vállalati adminisztrátorok jogköre. Egy kiadott felületet a vállalat minden tagja indíthat.

Miben különbözik a „Ping” a „Teszt kérés”től?

A Ping csak azt ellenőrzi, hogy a cím elérhető-e: token és adat nélkül. A Próbakérés mintaadatot küld, tokenrel együtt, és megjeleníti a teljes választ.

Biztonságos az API-tokenem?

Igen. A token titkosítva tárolódik, és soha nem kerül átadásra az ügyfeleknek. Az alkalmazás csak azt mutatja, hogy be van-e állítva a token, és mikor jár le.

Mely címek engedélyezettek végpontként?

Csak nyilvánosan elérhető https:// címek. A belső célok, például a localhost, a privát hálózatok vagy a felhő metaadatai elutasításra kerülnek: ez véd a felület visszaélése ellen.

Miért nem módosítható többé a kiadott interfész?

A célcím, a metódus, a mezők és a hitelesítési fejléc a kiadás után rögzített, így senki nem irányíthatja el csendben az adatok útvonalát. A token, annak lejáratideje és a közönség (csak a saját csapat, vagy partnercégek is) továbbra is módosítható; ez a módja annak, hogy lecseréld a lejárt tokent. Minden más esetben hozz létre egy új verziót.