Prilagođeni elementi: API

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

Postavite API sučelje

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

1. Stvaranje polja: Svako polje dobiva JSON ključ. S desne strane vidite uživo JSON pregled, koji se šalje vašem backendu upravo na taj način.
2. Adresa (URL): https:// adresa vašeg backenda. Dopuštene su samo HTTPS adrese i one javno dostupne (vidi Sigurnost u nastavku).
3. Metoda: POST (zadano), PUT, PATCH ili GET. Uz GET vrijednosti se dodaju kao upitni parametri umjesto slanja u tijelu zahtjeva.
4. Autentifikacija: Postavite naziv zaglavlja (npr. Authorization) i prefiks vrijednosti (npr. Bearer ), a zatim spremite token. Opcionalno postavite datum isteka.
5. Polja odgovora (opcionalno): Definirajte putem puta koje vrijednosti iz odgovora backenda trebaju biti prikazane: npr. order.id ili items[0].sku.
6. Provjerite s Ping i Test Request, zatim Release.

Sigurno pohranjivanje tokena

Token se pohranjuje šifriran i nikada se ne vraća klijentima: aplikacija prikazuje samo je li token postavljen i kada istječe. Pri slanju, Skava ga serveru 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 pritom ne šalje token niti podatke obrasca. Prikazuje dostupnost, status i vrijeme odgovora. Idealno kao prvi korak.
• Testni zahtjev : pravi probni pokret: šalje uzorke podataka uključujući token na vašu adresu i prikazuje vam kompletan odgovor te izdvojena polja odgovora.

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

Nacrt i objavljivanje

Svako sučelje počinje kao nacrt i može se slobodno uređivati. Kada je sve spremno, objavite ga putem opcije Objavi.

Sigurnost

Kako tim koristi objavljeno sučelje

Nakon što se sučelje objavi, svi članovi tvrtke mogu ga pokrenuti izravno iz razgovora: nije potreban uređivač. Tok je isti kao kod predložaka dokumenata: odabir, ispunjavanje, slanje.

1. U razgovoru dodirnite Plus na dnu i odaberite Prilagođeni element.
2. Odaberite željeni predložak ili sučelje s popisa.
3. Ispunite obrazac i Pošaljite.
4. 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 Skava asistentu u chatu, na primjer "napravi mi obrazac za narudžbu za moj katalog s količinom i adresom isporuke". On će na temelju toga stvoriti nacrt, kasnije možete pojedinačno mijenjati polja, a poznaje i vaš učitani katalog artikala: za narudžbe predlaže odabir proizvoda umjesto tekstualnog polja za broj artikla.

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

Što eksplicitno ne dira: token pristupa. Nikada ne traži niti prihvaća token, jer se poruke u chatu spremaju. Vi ga unosite sami u uređivaču, inače se ne šalje nijedan poziv. Također ne može objaviti: zadnji korak ostaje na vama, pa ništa ne postaje vidljivo kupcima bez provjere.

Tko ga može pokrenuti

Kartica "Točka pristupa" navodi tko može koristiti element. Zadano su to članovi vaše tvrtke. Druga postavka otvara ga vanjskim osobama, ali samo u chatu gdje je prisutan i netko iz vaše tvrtke: točno onaj slučaj za koji je namijenjen, kada vam kupac naručuje. Kada vaša tvrtka napusti chat, dozvola se automatski ukida.

Proizvodi iz vlastitog kataloga

Nakon što učitate katalog artikala, izgradnik nudi blok odabira proizvoda. Nema opcija za održavanje: popis je vaš katalog. Osoba koja naručuje pretražuje ga, vidi sliku, naziv i broj artikla, a vaš backend prima broj artikla. Skava odbacuje broj koji nije u vašem katalogu. Za količinu postavite obično polje za broj pored njega.

Definirajte karticu sami

Vaš backend odlučuje što kartica piše. Skava provjerava samo oblik, veličinu i sigurnost, nikada značenje: ne poznaje niti stanja narudžbe niti nazive polja. Da biste to učinili, 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 ne vrijedi kao kartica i primjenjuje se preslikavanje odgovora konfigurirano u elementu.
• state je samo boja i ikona: 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 nikada ne uspijeva zbog detalja.

Unosi korisnika pripadaju poslužitelju: ostaju nepromijenjeni bez obzira na to što vaš backend šalje. To je zapis u chatu o tome što je zapravo predano.

Prijavljenje statusa kasnije

Kada se element izvrši, Skava šalje dvije dodatne vrijednosti: callback_url i callback_token. Kasnije prijavite novo stanje na toj adresi i nova kartica se pojavi u chatu, također na mobitelu, dok netko gleda. Prethodna ostaje, pa je čitljivo koje je stanje prijavljeno. Pošaljite isti objekt card kao gore, putem POST s zaglavljem Authorization: Bearer <callback_token>. Uz karticu idu tri opcionalne vrijednosti:

• seq: vaš vlastiti brojilo. Izvještaj s manjom ili jednakom vrijednošću se odbacuje, pa dva izvještaja ne mogu jedan preteksti drugog.
• final: zatvara interakciju. Token postaje nevažeći, a kartica konačna.
• notify: postavite na false da se kartica objavi tiho, bez broja nepročitanih poruka 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. Isti izvještaj dvaput 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 Skavin sustavni pošiljatelj, ne osoba koja je pokrenula element niti račun vaše tvrtke. Tko je sustav koji piše navedeno je u naslovu kartice.

Potpuni primjer za kopiranje nalazi se u spremištu pod example_order_server/ i radi na api.skava.io.

Povezano

Želite li umjesto toga izraditi ispunjiv predložak dokumenta? Pogledajte Prilagođeni elementi: Dokumenti.

Često postavljana pitanja