Prilagojeni elementi: API

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

Nastavitev API vmesnika

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

1. Ustvarjanje polj: Vsako polje dobi JSON ključ. Na desni strani vidite v živo JSON predogled, ki se pošlje na vaš backend točno na ta način.
2. Naslov (URL): naslov https:// vašega backenda. Dovoljene so samo HTTPS in javno dostopne naslove (glejte varnost spodaj).
3. Metoda: POST (privzeto), PUT, PATCH ali GET. Pri GET se vrednosti dodajo kot parametri poizvedbe namesto da bi bile poslane v telesu.
4. Avtentikacija: Nastavite ime glave (npr. Authorization) in predpono vrednosti (npr. Bearer ), nato shranite žeton. Po želji nastavite datum poteka.
5. Polja odgovora (neobvezno): Določite po poti, katere vrednosti iz odgovora backenda 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 prikaže le ali je žeton nastavljen in kdaj poteče. Ob pošiljanju ga Skava na strani strežnika doda v nastavljeno glavo. Če nastavite datum poteka, Skava po poteku zavrne klic in vas prosi, da žeton obnovite.

Testiranje: Ping in Testni zahtevek

• Ping: preprosto preverjevanje dosegljivosti. Preveri le, ali vaš naslov odgovarja, pri tem pa ne pošlje žetona ali podatkov obrazca. Prikaže dosegljivost, status in čas odziva. Idealno kot prvi korak.
• Testni zahtevek: prava probna vožnja: pošlje vzorčne podatke, vključno z žetonom, na vaš naslov in prikaže celoten odgovor ter izločena polja odgovora.

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

Osnutek in objava

Vsak vmesnik se začne kot osnutek in ga lahko prosto urejate. Ko je vse pripravljeno, ga objavite z gumbom Objavi.

Varnost

Kako ekipa uporablja objavljen vmesnik

Ko je vmesnik objavljen, ga lahko vsi člani podjetja neposredno sprožijo iz klepeta, brez urejevalnika. Ni skupnega vnosa in ni vmesnega pogovornega okna: vsak objavljen element je v meniju plus pod svojim imenom, z logotipom podjetja, ki ga ponuja.

1. V klepetu pritisnite Plus na dnu in izberite želeni element, na primer Naročilo materiala.
2. Izpolnite obrazec in pritisnite Pošlji.
3. Rezultat se prikaže kot kartica v klepetu, vidna vsem udeležencem klepeta.

Pustite, da AI zgradi element

Kot administrator podjetja ne morate uporabljati urejevalnika sami. Povejte Skava pomočniku v klepetu, na primer "naredi mi obrazec za naročilo za moj katalog s količino in dostavno naslovom". Na podlagi tega ustvari osnutek, kasneje lahko polja spreminja eno za drugim in pozna vaš naložen katalog artiklov: za naročila predlaga izbirnik izdelkov namesto besedilnega polja za številko artikla.

Kaj lahko še nastavi: končno točko in metodo ter publiko ("samo člani podjetja" ali "tudi zunanji v istem klepetu"). Za publiko najprej vpraša, namesto da jo samo nastavi, ker določa, kdo lahko nekaj izvede od zunaj.

Kaj pa ne dotika: žetona za dostop. Nikoli ga ne zahteva in nikoli ga ne sprejme, ker se sporočila v klepetu shranjujejo. Vpišete ga sami v urejevalniku, sicer se klic ne pošlje. Tudi ne more objaviti: zadnji korak ostane pri vas, zato nič ne postane vidno strankam brez preverjanja.

Kdo ga lahko izvede

Zavihek "Končna točka" določa, kdo lahko uporabi element. Privzeto so to člani vašega podjetja. Druga nastavitve ga odpre tudi zunanjim osebam, vendar le v klepetu, kjer je prisoten tudi nekdo iz vašega podjetja: točno tisti primer, za katerega je namenjen, stranka, ki vam naroča. Ko vaše podjetje zapusti klepet, se dovoljenje samodejno preneha.

Izdelki iz vašega lastnega kataloga

Ko naložite katalog artiklov, vam graditelj ponudi blok izbirnika izdelkov. Ni možnosti za vzdrževanje: seznam je vaš katalog. Oseba, ki naroča, ga išče, vidi sliko, ime in številko artikla, vaš backend pa prejme številko artikla. Skava zavrže številko, ki ni v vašem katalogu. Za količino postavite običajno polje za številko poleg tega.

Kartico določite sami

Vaš backend odloči, kaj kartica vsebuje. Skava preverja le obliko, velikost in varnost, nikoli pa pomen: ne pozna niti stanj naročila niti imen polj. Za to 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 tega odgovor ne šteje kot kartica in se uporabi preslikava odgovora, ki je nastavljena v elementu.
• state je samo barva in ikona: ok, pending, warn ali error. Vse, kar nosi pomen, se vpiše v status_text kot prosti besedilni zapis.
• fields je seznam oznak in vrednosti, največ 20 vnosov. Predolge vrednosti se skrajšajo namesto da bi bile zavržene, zato naročilo nikoli ne odpade zaradi podrobnosti.

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

Poročanje o stanju kasneje

Ko se element izvede, Skava pošlje dve dodatni vrednosti: callback_url in callback_token. Kasneje tam poročite 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čeno. Pošljite isti objekt card kot zgoraj, prek POST z glavo Authorization: Bearer <callback_token>. Trije neobvezni podatki gajo poleg kartice:

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

Interakcija lahko objavi največ 50 kartic. Dvakrat isto poročilo ne ustvari druge kartice.

Skava odgovori s 200 in seznamom hints, če je bilo kaj okrajš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 podjetja. Kateri sistem piše, je navedeno v naslovu kartice.

Celoten primer za kopiranje najdete v repozitoriju v mapi example_order_server/ in je dostopen na api.skava.io.

Povezane vsebine

Želite namesto tega ustvariti obrazec za izpolnjevanje? Oglejte si Prilagojeni elementi: Dokumenti.

Pogosta vprašanja