Prilagođeni elementi: API

Sučelje API je obrazac čije popunjene vrijednosti Skava šalje kao JSON na adresu koju odredite (vaš backend). Na taj način možete sigurno povezati Skavu s vlastitim sustavima.

Postavite sučelje API

Sučelje se sastoji od polja za unos (ona čine JSON), ciljne adrese i autentifikacije.

1. Stvaranje polja: Svako polje dobiva JSON ključ. Desno vidite JSON pregled uživo, koji se šalje na vaš backend upravo na ovaj način.
2. Adresa (URL): https:// adresa vašeg backend-a. Dozvoljene su samo HTTPS adrese i javno dostupne adrese (vidite Sigurnost ispod).
3. Metoda: POST (zadano), PUT, PATCH ili GET. Kod GET vrijednosti se dodaju kao parametri upita umjesto da se šalju u tijelu zahtjeva.
4. Autentifikacija: Postavite naziv zaglavlja (npr. Authorization) i prefiks vrijednosti (npr. Bearer ), a zatim spremite token. Po želji postavite datum isteka.
5. Polja odgovora (neobavezno): Definirajte putem putanje koje vrijednosti iz odgovora backend-a trebaju biti prikazane: npr. order.id ili items[0].sku.
6. Provjerite pomoću Ping i Test Request, zatim Release.

Sigurno pohranite token

Token se pohranjuje šifrirano i nikad se ne vraća klijentima: aplikacija prikazuje samo je li token postavljen i kada istječe. Pri slanju, Skava ga server-side dodaje u konfiguriranu zaglavlje. Ako postavite datum isteka, Skava odbija poziv nakon isteka i traži da obnovite token.

Testiranje: Ping i Testni zahtjev

• Ping: provjera dostupnosti. Provjerava samo odgovara li vaša adresa, a pri tome ne šalje token niti podatke obrasca. Prikazuje dostupnost, status i vrijeme odgovora. Idealno kao prvi korak.
• Testni zahtjev: stvarni probni pokret: šalje uzorak podataka uključujući token na vašu adresu i prikazuje vam potpuni odgovor kao i izdvojena polja odgovora.

Kao administrator, možete pokrenuti oba dok ste još u nacrtu kako biste provjerili integraciju prije objave.

Izrada i objavljivanje

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

Sigurnost

Kako tim koristi objavljeni sučelje

Nakon što se sučelje objavi, svi članovi tvrtke mogu ga pokrenuti izravno iz chata, bez potrebe za uređivačem. Ne postoji kolektivni unos ni međusobni dijalog: svaki objavljeni element nalazi se u plus izborniku pod svojim imenom, uz logotip tvrtke koja ga nudi.

1. U chatu dodirnite Plus na dnu i dodirnite element koji želite, na primjer Naručivanje materijala.
2. Ispunite obrazac i dodirnite Pošalji.
3. Rezultat se prikazuje kao kartica u chatu, vidljiva svima u chatu.

Neka AI izgradi element

Kao administrator tvrtke, ne morate sami koristiti uređivač. Recite Skavinom asistentu u chatu, na primjer "izradi mi obrazac za narudžbu za moj katalog s količinom i adresom za dostavu". Na temelju toga stvara nacrt, kasnije može mijenjati polja jedno po jedno i poznaje vaš učitani katalog artikala: za narudžbe predlaže odabir proizvoda umjesto tekstualnog polja za broj artikla.

Može postaviti i: endpoint i metodu te publiku ("samo članovi tvrtke" ili "i vanjske osobe u istom chatu"). Za publiku prvo pita umjesto da je odmah postavi, jer ona određuje tko može pokrenuti nešto izvana.

Ono što izričito ne dira: token za pristup. Nikad ga ne traži i nikad ga ne prihvaća, jer se poruke u chatu spremaju. Vi ga sami unesete u uređivaču, inače ne ide nijedan poziv. I ne može objaviti: zadnji korak ostaje na vama, pa ništa ne postane vidljivo klijentima bez provjere.

Tko ga može pokrenuti

Zabilješka "Endpoint" kaže tko može koristiti element. Zadano su članovi vaše tvrtke. Druga postavka otvara ga za vanjske osobe, ali samo u chatu gdje je prisutan i netko iz vaše tvrtke: točno slučaj za koji je predviđena, klijent koji naručuje od vas. Kada vaša tvrtka napusti chat, dopuštenje automatski istječe.

Proizvodi iz vlastitog kataloga

Nakon što učitavate katalog artikala, izvođač dobiva blok odabira proizvoda. Nema opcija za održavanje: popis je vaš katalog. Osoba koja naručuje ga pretražuje, 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 brojke pored njega.

Definirajte karticu sami

Vaš backend odlučuje što kartica sadrži. Skava provjerava samo oblik, veličinu i sigurnost, nikad značenje: ne zna niti stanja narudžbi niti imena polja. Za to odgovorite objektom card:

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

• v mora biti cijeli broj 1. Bez njega odgovor se ne računa kao kartica i primjenjuje se preslikavanje odgovora postavljeno u elementu.
• state sadrži samo boju i ikonu: ok, pending, warn ili error. Sve što nosi značenje ide u status_text kao slobodan tekst.
• fields je popis oznaka i vrijednosti, najviše 20 stavki. Preduge vrijednosti se skraćuju umjesto da se odbace, pa narudžba nikad ne propadne zbog sitnice.

Unosi korisnika pripadaju poslužitelju: ostaju netaknuti bez obzira što vaš backend pošalje. To je zapis u chatu o tome što je stvarno poslano.

Prijavljenje statusa kasnije

Kada se element pokrene, Skava šalje dvije dodatne vrijednosti: callback_url i callback_token. Kasnije prijavite novo stanje na tom mjestu i nova kartica se pojavi u chatu, i na telefonu, dok netko gleda. Prethodna ostaje, pa je vidljivo koje je stanje prijavljeno. Pošaljite isti objekt card kao gore, putem POST s zaglavljem Authorization: Bearer <callback_token>. Tri opcionalne vrijednosti idu uz karticu:

• seq: vaš vlastiti brojač. Izvještaj s manjom ili jednakom vrijednošću se odbacuje, pa dva izvještaja ne mogu međusobno preteći.
• final: zatvara interakciju. Token postaje nevažeći, a kartica je završna.
• notify: postavite na false da biste karticu objavili tiho, bez broja nepročitanih i bez obavijesti. Za međukorake koji ne bi trebali probuditi nikoga. Bez toga, kartica je potpuno normalna poruka.

Interakcija može objaviti najviše 50 kartica. Dva puta isti izvještaj ne stvara drugu karticu.

Skava odgovara s 200 i popisom hints ako je nešto skraćeno ili izbačeno, te s 422 ako je kartica bila neupotrebljiva. Interakcija prihvaća izvještaje 90 dana.

Kartice objavljuje sustavni pošiljatelj Skave, a ne osoba koja je pokrenula element niti račun vaše tvrtke. Tko je sustav koji piše, navedeno je u naslovu kartice.

Kompletni primjer za kopiranje nalazi se u repozitoriju pod example_order_server/ i pokreće se na api.skava.io.

Povezano

Želite li umjesto toga izraditi ispunjivi predložak dokumenta? Pogledajte Custom Elements: Documents.

Česta pitanja