Prilagojeni elementi: vmesnik API

Vmesnik API je obrazec, katerega izpolnjene vrednosti Skava pošlje kot JSON na naslov, ki ga določite (vaš backend). Tako lahko Skava varno povežete s svojimi sistemi.

Nastavitev vmesnika API

Vmesnik sestavljajo vhodna polja (ki tvorijo JSON), ciljni naslov in overjanje.

1. Ustvarite polja: Vsako polje dobi JSON ključ. Na desni vidite predogled JSON v živo, ki se bo vašemu strežniku poslal točno v tej obliki.
2. Naslov (URL): https:// naslov vašega strežnika. Dovoljeni so le naslovi s HTTPS in javno dostopni (glejte varnost spodaj).
3. Metoda: POST (privzeto), PUT, PATCH ali GET. Pri GET se vrednosti dodajo kot parametri poizvedbe namesto, da bi se poslale v telesu zahtevka.
4. Overjanje: Nastavite ime glave (npr. Authorization) in predpono vrednosti (npr. Bearer ), nato shranite žeton. Po želji nastavite datum poteka.
5. Polja odziva (opcijsko): Določite s potjo, katere vrednosti iz odziva strežnika naj se prikažejo: npr. order.id ali items[0].sku.
6. Preverite s Ping in Test Request, nato Release.

Shranite žeton varno

Žeton je shranjen šifriran in se nikoli ne vrne strankam: aplikacija prikazuje le, ali je žeton nastavljen in kdaj poteka. Ob pošiljanju ga aplikacija Skava doda na strežniški strani na konfigurirano glavo. Če nastavite datum poteka, aplikacija Skava zavrne klic po poteku in vas prosi za obnovo žetona.

Preizkušanje: Ping in preizkusna zahteva

• Ping : preverjanje dosegljivosti. Preveri le, ali vaš naslov odgovarja, pri tem pa ne pošilja žetona ali podatkov obrazca. Prikaže dosegljivost, status in čas odziva. Idealno kot prvi korak.
• Preizkusni zahtevek : pravi preizkusni zagon: pošlje vzorne podatke, vključno z žetonom, na vaš naslov in prikaže celoten odziv ter izločena polja odziva.

Kot skrbnik lahko oba opravite še v načinu osnutka, da preverite integracijo pred objavo.

Osutek in objava

Vsak vmesnik se začne kot osutek in ga je mogoče prosto urejati. Ko je vse pripravljeno, ga objavite s klikom na Objavi.

Varnost

Kako ekipa uporablja objavljeno vmesnik

Ko je vmesnik objavljen, ga lahko vsi člani podjetja neposredno sprožijo iz klepeta: urejevalnik ni potreben. Postopek je enak kot pri predlogah dokumentov: izberite, izpolnite, pošljite.

1. V klepetu pritisnite Plus na dnu in izberite Prilagojen element.
2. Iz seznama izberite želeno predlogo ali vmesnik.
3. Izpolnite obrazec in pritisnite Pošlji.
4. Rezultat se prikaže kot kartica v klepetu: vidna je vsem udeležencem v klepetu.

Pustite, da umetna inteligenca ustvari element

Kot skrbnik podjetja ne morate uporabljati urejevalnika sami. Povejte asistentu Skava v klepetu, na primer »ustvari mi obrazec za naročilo za moj katalog s količino in naslovom za dostavo«. Iz tega ustvari osnutek, kasneje pa lahko polja spreminja eno po eno. Pozna vaš naložen katalog izdelkov: za naročila predlaga izbirnik izdelkov namesto besedilnega polja za številko izdelka.

Kar lahko nastavi tudi: končno točko in metodo ter publiko (»samo člani podjetja« ali »tudi zunanji uporabniki v istem klepetu«). Pri publiko najprej vpraša, namesto da bi jo takoj nastavil, saj odloča, kdo lahko zunanje izvaja določene stvari.

Kar eksplicitno ne dotakne: žeton za dostop. Nikoli ga ne zahteva in nikoli ga ne sprejme, ker se sporočila v klepetu shranjujejo. Vnesete ga sami v urejevalniku, sicer se klic ne izvede. Tudi ne more objaviti: zadnji korak ostane pri vas, zato ničesar ne postane vidnega strankam brez vaše preveritve.

Kdo ga lahko izvaja

Zavihek »Končna točka« določa, kdo lahko uporabi element. Privzeto so to člani vašega podjetja. Druga nastavitev ga odpre tudi zunanjim uporabnikom, vendar le v klepetu, kjer je prisoten tudi nekdo iz vašega podjetja: točno tisti primer, za katerega je namenjen, ko stranka pri vas naroča. Ko vaše podjetje zapusti klepet, se dovoljenje samodejno prekliče.

Izdelki iz vašega lastnega kataloga

Ko boste naložili katalog izdelkov, vam bo urejevalnik ponudil blok izbirnika izdelkov. Možnosti za vzdrževanje ni: seznam je vaš katalog. Oseba, ki naroča, ga poišče, vidi sliko, ime in artiklno številko, vaš backend pa prejme artiklno številko. Skava zavrne številko, ki ni v vašem katalogu. Za količino postavite običajno polje za številke ob njem.

Kartico določite sami

Vaš backend odloča, kaj piše na kartici. Skava preveri le obliko, velikost in varnost, nikoli pa pomena: ne pozna niti stanj naročil niti imen polj. Da to storite, odgovorite z objektom card:

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

• v mora biti celo število 1. Brez njega odgovor ne šteje kot kartica in velja preslikava odgovora, konfigurirana v elementu.
• state je le barva in ikona: ok, pending, warn ali error. Vse, kar nosi pomen, se vpiše v status_text kot prost besedilo.
• fields je seznam oznak in vrednosti, največ 20 vnosov. Pre dolge vrednosti se skrajšajo namesto da bi bile zavrnjene, zato naročilo nikoli ne odpove zaradi podrobnosti.

Vnosi uporabnika pripadajo strežniku: ostanejo nespremenjeni, ne glede na to, kaj pošlje vaš backend. To je zapis v klepetu o tem, kaj je dejansko oddano.

Poročanje o stanju kasneje

Ko element teče, Skava pošlje dve dodatni vrednosti: callback_url in callback_token. Tam kasneje poročajte novo stanje in v klepetu se pojavi nova kartica, tudi na telefonu, medtem ko nekdo gleda. Prejšnja ostane, zato je razvidno, katero stanje je bilo poročano. Pošljite enak objekt card kot zgoraj, prek POST z glavo Authorization: Bearer <callback_token>. Ob kartici se pošljejo trije izbirni parametri:

• seq: vaš lastni števec. Poročilo z manjšo ali enako vrednostjo se zavrne, zato se dve poročili ne moreta prehiteti.
• final: zaključi interakcijo. Žeton postane neveljaven in kartica je dokončna.
• notify: nastavite na false, da se kartica objavi tiho, brez števila neprebranih sporočil in brez obvestila. Primerno za vmesne korake, ki ne bi smeli prebuditi nikogar. Brez tega je kartica povsem običajno sporočilo.

Interakcija lahko objavi največ 50 kartic. Enako poročilo dvakrat ne ustvari druge kartice.

Skava odgovori s 200 in seznamom hints, če je bilo kaj skrajšano ali izpuščeno, ter s 422, če je bila kartica neuporabna. Interakcija sprejema poročila 90 dni.

Kartice objavi sistemski pošiljatelj Skave, ne oseba, ki je izvedla element, in ne račun vaše lastne družbe. V naslovu kartice je navedeno, kateri sistem je avtor.

Celoten primer za kopiranje je na voljo v repozitoriju pod example_order_server/ in deluje na api.skava.io.

Sorazno

Želite namesto tega ustvariti izpolnjevani predlog dokumenta? Glejte Prilagojeni elementi: dokumenti.

Pogosta vprašanja