Prilagođeni elementi: API

API interfejs je obrazac čije popunjene vrednosti Skava šalje kao JSON na adresu koju vi navedete (vaš backend). Na ovaj način možete bezbedno povezati Skavu sa sopstvenim sistemima.

Podešavanje API interfejsa

Interfejs se sastoji od polja za unos (ona formiraju JSON), ciljne adrese i autentifikacije.

1. Kreiranje polja: Svako polje dobija JSON ključ. Desno vidite uživo JSON pregled, koji se šalje vašem backendu na ovaj način.
2. Adresa (URL): https:// adresa vašeg backenda. Dozvoljene su samo HTTPS i javno dostupne adrese (vidite Bezbednost ispod).
3. Metoda: POST (podrazumevano), PUT, PATCH ili GET. Kod GET vrednosti se dodaju kao parametri upita umesto da se šalju u telu zahteva.
4. Autentifikacija: Podesite naziv zaglavlja (npr. Authorization) i prefiks vrednosti (npr. Bearer ), zatim sačuvajte token. Po želji podesite datum isteka.
5. Polja odgovora (opciono): Definišite putem puta koje vrednosti iz odgovora backenda treba prikazati: npr. order.id ili items[0].sku.
6. Proverite pomoću Ping i Test Request, zatim Release.

Bezbedno čuvanje tokena

Token se čuva šifrovano i nikada se ne vraća klijentima: aplikacija prikazuje samo da li je token podešen i kada ističe. Pri slanju, Skava ga dodaje serveru u podešeni zaglavlje. Ako podesite datum isteka, Skava odbija poziv nakon isteka i traži da obnovite token.

Testiranje: Ping i Test zahtev

• Ping: provera dostupnosti. Proverava samo da li vaša adresa odgovara, a pri tome ne šalje token niti podatke obrasca. Prikazuje dostupnost, status i vreme odgovora. Idealno kao prvi korak.
• Testni zahtev: prava proba: šalje uzorak podataka uz token na vašu adresu i prikazuje kompletan odgovor kao i izvađena polja odgovora.

Kao administrator, možete pokrenuti oba dok ste još u nacrtu, da biste potvrdili integraciju pre objavljivanja.

Skica i objavljivanje

Svako sučelje počinje kao skica i može se slobodno uređivati. Kada je sve spremno, objavljujete ga pomoću opcije Objavi.

Bezbednost

Kako tim koristi objavljen interfejs

Čim se interfejs objavi, svi članovi kompanije mogu ga pokrenuti direktno iz čata, bez potrebe za editorom. Ne postoji zajednički unos niti međusobni dijalog: svaki objavljen element se nalazi u plus meniju pod svojim imenom, uz logo kompanije koja ga nudi.

1. U čatu, dodirnite Plus na dnu i dodirnite element koji želite, na primer Narudžbina materijala.
2. Popunite obrazac i Pošaljite.
3. Rezultat se prikazuje kao kartica u čatu, vidljiva svima u tom čatu.

Neka veštačka inteligencija napravi element

Kao administrator firme, ne morate sami koristiti editor. Recite Skava asistentu u chatu, na primer: „Napravi mi obrazac za narudžbinu za moj katalog sa količinom i adresom za dostavu“. Na osnovu toga on kreira nacrt, kasnije može menjati polja jedno po jedno i poznaje vaš učitani katalog artikala: za narudžbine predlaže birač proizvoda umesto tekstualnog polja za broj artikla.

Ono što takođe može podesiti: endpoint i metod kao i publiku („samo članovi firme“ ili „takođe spoljni korisnici u istom chatu“). Za publiku prvo pita umesto da odmah podesi, jer to određuje ko sme da pokrene nešto spolja.

Ono što eksplicitno ne dira: token za pristup. Nikada ga ne traži i nikada ga ne prihvata, jer se poruke u chatu čuvaju. Vi ga sami unosite u editoru, inače se ne šalje nijedan poziv. I ne može da objavi: poslednji korak ostaje na vama, tako da ništa ne postane vidljivo klijentima bez provere.

Ko sme da ga pokrene

Kartica „Endpoint“ govori ko sme da koristi element. Podrazumevano su to članovi vaše firme. Druga podešavanja otvara ga za spoljne korisnike, ali samo u chatu gde je prisutan i neko iz vaše firme: tačno onaj slučaj za koji je namenjeno, klijent koji naručuje od vas. Kada vaša firma napusti chat, dozvola automatički ističe.

Proizvodi iz vašeg kataloga

Kada učitate katalog artikala, izvođač dobija blok izbor proizvoda. Nema opcija za održavanje: lista je vaš katalog. Osoba koja naručuje pretražuje katalog, vidi sliku, naziv i broj artikla, a vaš backend prima broj artikla. Skava odbija broj koji nije u vašem katalogu. Za količinu, postavite obično polje za broj pored njega.

Definišite karticu sami

Vaš backend odlučuje šta kartica sadrži. Skava proverava samo oblik, veličinu i bezbednost, nikada značenje: ne zna niti stanja narudžbine, niti imena polja. Da biste to uradili, odgovorite objektom card:

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

• v mora biti ceo broj 1. Bez njega odgovor se ne računa kao kartica i primenjuje se mapiranje odgovora podešeno u elementu.
• state sadrži samo boju i ikonicu: ok, pending, warn ili error. Sve što nosi značenje ide u status_text kao slobodan tekst.
• fields je lista oznaka i vrednosti, najviše 20 stavki. Preduge vrednosti se skraćuju, a ne odbacuju, pa narudžbina ne uspeva zbog sitnice.

Unosi korisnika pripadaju serveru: ostaju netaknuti bez obzira šta vaš backend pošalje. To je zapis u čatu o tome šta je stvarno poslatо.

Prijavljivanje statusa kasnije

Kada se element izvrši, Skava šalje dve dodatne vrednosti: callback_url i callback_token. Kasnije prijavite novo stanje tamo i nova kartica se pojavljuje u čatu, i na telefonu, dok neko gleda. Prethodna ostaje, pa je vidljivo koje je stanje prijavljeno. Pošaljite isti objekat card kao gore, putem POST sa zaglavljem Authorization: Bearer <callback_token>. Tri opcionalne vrednosti idu pored kartice:

• seq: vaš sopstveni brojač. Izveštaj sa manjom ili jednakom vrednošću se odbacuje, pa dva izveštaja ne mogu da se preteknu.
• final: završava interakciju. Token postaje nevažeći, a kartica je konačna.
• notify: postavite na false da biste objavili karticu tiho, bez broja nepročitanih i bez obaveštenja. Za međukorake koji ne bi trebalo da probude nikoga. Bez ove opcije, kartica je potpuno normalna poruka.

Interakcija može da objavi najviše 50 kartica. Isti izveštaj dva puta ne stvara drugu karticu.

Skava odgovara sa 200 i listom hints ako je nešto skraćeno ili izbačeno, i sa 422 ako je kartica bila neupotrebljiva. Interakcija prihvata izveštaje 90 dana.

Kartice objavljuje sistemski pošiljalac Skave, a ne osoba koja je pokrenula element niti nalog vaše firme. Čiji je sistem pisao navedeno je u naslovu kartice.

Kompletan primer za kopiranje nalazi se u repozitorijumu pod example_order_server/ i pokreće se na api.skava.io.

Povezano

Želite li umesto toga da napravite ispunjivi šablon dokumenta? Pogledajte Custom Elements: Dokumenti.

Česta pitanja