Egyedi elemek: API

Az API-felület egy űrlap, amelynek kitöltött értékeit a Skava JSON formátumban elküldi egy Ön által megadott címre (a saját backendjére). Ezzel a módszerrel biztonságosan összekötheti a Skavát a saját rendszereivel.

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

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

1. Mezők létrehozása: Minden mező kap egy JSON-kulcsot. A jobb oldalon élőben látható a JSON-előnézet, amely pontosan így kerül elküldésre a backend-re.
2. Cím (URL): a backend https:// címe. Csak HTTPS és nyilvánosan elérhető címek engedélyezettek (lásd lentebb a Biztonság részt).
3. Módszer: POST (alapértelmezett), PUT, PATCH vagy GET. A GET esetén az értékek lekérdezési paraméterként csatlakoznak, nem a testben kerülnek elküldésre.
4. Hitelesítés: Adja meg a fejléc nevét (pl. Authorization) és az érték előtagját (pl. Bearer ), majd mentse el a tokent. Opcionálisan állíthat lejárati dátumot.
5. Válaszmezők (opcionális): Határozza meg útvonal szerint, hogy a backend válaszból mely értékeket jelenítse meg: pl. order.id vagy items[0].sku.
6. Ellenőrizze a Ping és a Kérés tesztelése funkciókkal, majd Közzéteszi.

Tárolja biztonságosan a tokent

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

Tesztelés: Ping és kérés tesztelése

• Ping : egy könnyű elérhetőségi ellenőrzés. Csak azt vizsgálja, hogy reagál-e a cím, és nem küld token-t vagy űrlapadatokat a folyamat során. Megjeleníti az elérhetőséget, az állapotot és a válaszidőt. Ideális első lépésként.
• Próbakérés : a valódi tesztüzem: mintaadatokat, beleértve a tokent is küld a címére, és megjeleníti a teljes választ, valamint a kinyert válaszmezőket.

Adminisztrátorként mindkettőt futtathatja még tervezet módban is, hogy ellenőrizze az integrációt a kiadás előtt.

Tervezet és közzététel

Minden felület tervezetként indul, és szabadon szerkeszthető. Amikor minden készen áll, a Közzététel gombbal teszi közzé.

Biztonság

Hogyan használja a csapat egy kiadott felületet

Amint egy felület megjelenik, a cég minden tagja közvetlenül egy beszélgetésből indíthatja el: nincs szükség szerkesztőre. A folyamat ugyanaz, mint a dokumentumsablonoknál: kiválasztás, kitöltés, küldés.

1. A beszélgetésben koppintson az alján található Plusz gombra, majd válassza a Egyéni elem lehetőséget.
2. Válassza ki a kívánt sablont vagy felületet a listából.
3. Töltse ki az űrlapot, majd nyomja meg a Küldés gombot.
4. Az eredmény egy kártyaként jelenik meg a csevegésben: mindenki számára látható a csevegésben.

Hagyja, hogy a mesterséges intelligencia hozzon létre egy elemet

Cégadminként nem kell magának használnia a szerkesztőt. Mondja meg a Skava asszisztensnek a csevegésben például, hogy „készítsen nekem rendelési űrlapot a katalógusomhoz mennyiséggel és szállítási címmel". Ebből egy tervezetet készít, később mezőnként módosíthatja, és ismeri a feltöltött cikkkatalógusát: rendelések esetén a cikkszámhoz nem szöveges mezőt, hanem termékválasztót javasol.

Mit állíthat be még: a végpontot és a metódust, valamint a célcsoportot („csak cégtagok" vagy „külsősök is ugyanabban a csevegésben"). A célcsoportot nem állítja be azonnal, hanem először megkérdezi, mert ez dönti el, ki futtathat kívülről valamit.

Mit nem érint explicit módon: a hozzáférési tokent. Soha nem kér ilyet, és soha nem fogad el, mivel a csevegési üzenetek tárolásra kerülnek. Ezt Ön adja be a szerkesztőben, különben nem indul ki hívás. És nem is teheti közzé: az utolsó lépés Önnél marad, így semmi nem válik ellenőrizetlenül láthatóvá az ügyfelek számára.

Ki futtathatja

A „Végpont" fül jelzi, ki használhatja az elemet. Az alapértelmezés a cég tagjai. A második beállítás megnyitja a külsősök előtt is, de csak olyan csevegésben, ahol a cégük egy tagja is jelen van: pontosan arra az esetre, amire szánták, amikor az ügyfél rendel Öntől. Amikor a cég elhagyja a csevegést, a jogosultság magától megszűnik.

Saját katalógusából származó termékek

Ha feltöltötte a cikk-katalógusát, a szerkesztő egy termékválasztó blokkot kínál. Nincs beállítási lehetőség: a lista maga a katalógus. A rendelést leadó személy keres a listában, látja a képet, a nevet és a cikkszámot, a háttérendszere pedig megkapja a cikkszámot. A Skava elutasítja a katalógusban nem szereplő számot. A mennyiséghez helyezzen mellé egy szokásos számmezőt.

Definiálja a kártyát saját maga

A háttérendszere dönti el, mit ír a kártya. A Skava csak a formát, a méretet és a biztonságot ellenőrzi, soha a jelentést: nem ismeri a rendelési állapotokat vagy a mezőneveket. Ehhez válaszoljon egy card objektummal:

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

• A v értékének a 1 egész számnak kell lennie. Enélkül a válasz nem számít kártyának, és az elembe konfigurált válaszleképezés lép életbe.
• state csak színt és ikont jelent: ok, pending, warn vagy error. Minden jelentéssel bíró tartalom a status_text mezőbe kerül szabad szövegként.
• fields egy címkék és értékek listája, maximum 20 bejegyzéssel. A túl hosszú értékeket lerövidítik, nem pedig elutasítják, így egy megrendelés sosem bukik meg egy részlet miatt.

A felhasználó adatai a szerver tulajdonát képezik: azok változatlanok maradnak, függetlenül attól, amit a backend küld. Ezek a csevegésben rögzített nyilvántartás arról, amit valójában beküldtek.

Státusz későbbi jelentése

Amikor az elem fut, a Skava két extra értéket küld: callback_url és callback_token. Később küldjön ide egy új státuszt, és egy új kártya jelenik meg a csevegésben, a telefonon is, miközben valaki éppen nézi. Az előző kártya megmarad, így olvasható, hogy melyik státuszt jelentették. Küldje el ugyanazt a card objektumot, mint fent, POST kéréssel, Authorization: Bearer <callback_token> fejléccel. A kártya mellé három opcionális érték is tartozik:

• seq: saját számlálója. A kisebb vagy egyenlő értékű jelentést elvetik, így két jelentés nem előzheti meg egymást.
• final: lezárja a kölcsönhatást. A token érvénytelenné válik, és a kártya végleges.
• notify: állítsa false értékre, hogy a kártya csendesen kerüljön közzétételre, olvasatlan számláló és értesítés nélkül. Az olyan köztes lépésekhez, amelyek nem ébresztenek senkit. Enélkül a kártya egy tökéletesen normális üzenet.

Egy kölcsönhatás legfeljebb 50 kártyát tölthet fel. Ugyanaz a jelentés kétszer nem hoz létre második kártyát.

A Skava 200 kóddal és egy hints listával válaszol, ha bármit lerövidítettek vagy eldobtak, és 422 kóddal, ha a kártya használhatatlan volt. Egy kölcsönhatás 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ége fiókjából. A kártya címében szerepel, melyik rendszer írta azt.

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

Kapcsolódó

Inkább egy kitölthető dokumentumsablont szeretne létrehozni? Lásd a Egyedi elemek: Dokumentumok oldalt.

Gyakran ismételt kérdések