Skava Skava / Wiki

Povezivanje prilagođenih elemenata za developere

Ova stranica je namenjena developerima koji povezuju backend kompanije sa Skavom. Kako se kreira i objavljuje API element objašnjeno je na stranici Prilagođeni elementi: API interfejsi; ovde pokrivamo sve što se dešava na drugom kraju linije.

Ideja u jednoj rečenici: Skava ne poznaje vašu domenu. Poznaje tačno jedan format, a to je kartica. Vi odlučujete šta ona sadrži, mi proveravamo samo oblik, veličinu i bezbednost. Narudžbina materijala je jedan primer; sledeća kompanija prikuplja povratne informacije korisnika, a ona posle te arhivira fotografije sa gradilišta u svojim evidencijama.

Pregled procesa

  1. Administrator kompanije kreira API element u Skavi: obrazac, adresa vašeg backend-a, metod i token.
  2. Neko u četu popuni obrazac i pošalje ga.
  3. Skava poziva vaš backend i šalje popunjene vrednosti kao JSON.
  4. Vaš odgovor postaje karta u četu.
  5. Po želji, kasnije prijavljujete nova stanja putem callback-a. Svako prijavljivanje postaje nova karta, a prethodna ostaje.

Zahtevi za vaš backend

  • HTTPS. Samo https://, bez http, bez podataka za prijavu u adresi, najviše 2000 znakova.
  • Javno dostupno. Domet mora da rešava isključivo na javne IP adrese. Lokalni host, privatne mreže, link-local i cloud metapodaci se odbacuju, a to se proverava pri svakom pozivu.
  • Fiksna adresa. Skava rešava domet jednom i vezuje konekciju za tu IP adresu. Promena DNS-a tokom poziva nema uticaja.
  • Bez preusmeravanja. Preusmeravanje 301 na „tačnu“ adresu računa se kao neuspeh. Unesite konačnu adresu odmah.
  • Vreme odgovora. Vreme isteka se podešava po elementu, a maksimalno je ograničeno na 30 sekundi. Ako vam treba duže, odgovorite odmah i prijavite rezultat kasnije putem povratnog poziva.
  • Veličina odgovora. Skava čita najviše 256 KiB.
  • Content-Type. Telo se parsira samo ako je application/json.

Zahtev koji stiže do vas

Metod je GET, POST, PUT ili PATCH, u zavisnosti od elementa. Kod POST, PUT i PATCH vrednosti stižu kao JSON telo, a kod GET kao parametri upita.

Autentifikacija je jedan zaglavlje čije je ime i prefiks vrednosti podešeni u elementu, obično Authorization sa prefiksom Bearer . Token se čuva šifrovano na našoj strani. Zaglavlja host, content-length, content-type, cookie i accept-encoding ne mogu se postaviti.

Telo je ravni objekat. Ključeve bira onaj ko je napravio element; ugnježdenje se pojavljuje samo tamo gde su dodali tabelu ili birač proizvoda:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Tri ključa uvek dolaze od nas, pa ih ne koristite sami:

  • locale: jezički kod korisnika. Odgovarajte na tom jeziku; mi ne prevodimo vaše tekstove.
  • callback_url i callback_token: povratni poziv za ovo jedno interakciju, vidi ispod. Prisutni su samo kada poziv dolazi iz čata.

Polja konteksta kao što su ime, kompanija, projekat ili podrazgovor popunjava sam server, izvedena iz kanala u kojem je element pokrenut. Klijent koji je izmenjen ne može tamo da tvrdi drugo ime projekta.

Odgovor: format kartice

Odgovori sa 2xx i objektom card. To je tačno ono što postaje kartica u čatu:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (obavezno): celobrojna vrednost 1. Kao tekst ("1") odbija se. Bez nje odgovor se ne računa kao kartica i primenjuje se mapiranje odgovora podeseno u elementu.
  • title: naslov kartice.
  • state: samo boja i ton ikone, jedna od vrednosti ok, pending, warn, error. Nepoznata vrednost se vraća na ok i dobijaš napomenu.
  • status_text: slobodan tekst koji ne tumačimo. Nalazi se na vrhu kartice i prikazuje se u listu razgovora i u obaveštenju.
  • fields: lista label i value. Najviše 20 stavki, label 80 znakova, value 200, title i status_text po 120. Vrednosti koje su predugačke se skraćuju, a ne odbacuju: narudžbina ne bi trebalo da ne uspe zbog sitnice.
  • icon: pogledajte ispod.

Šta Skava radi sa vašim tekstovima pre nego što stignu u razgovor: prelomi redova i kontrolni znaci se uklanjaju (znak za pisanje sdesna nalevo bi inače mogao da promeni prikaz iznosa), backtickovi se zamenjuju, a sve što počinje sa [SKAVA: se neutrališe. Poslednje sprečava da se vrednost na kartici protumači kao neki drugi element razgovora, na primer zahtev za plaćanje.

Linkovi u poljima, HTML i slike se ne mogu postaviti. Razgovor je poverljivo okruženje, a klikabilna adresa sa stranog backend-a bila bi pozivnica da se ponovo izgradi stranica za prijavu.

Unosi korisnika pripadaju serveru: pojavljuju se na prvoj kartici i ne možete ih prepisati. U čatu predstavljaju zapis onoga što je stvarno poslato.

Ikone

Koristeći icon, kartica dobija svoj znak u zaglavlju. Dva načina:

Ime iz priloženog skupa: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Ili vaš sopstveni SVG kao niz znakova. Iz njega Skava uzima samo geometriju (path, circle, ellipse, rect, line, polyline, polygon sa njihovim numeričkim atributima) i gradi svoju sliku. Skripte, stilovi, spoljne reference, foreignObject i atributi događaja se odbacuju; doctype ili entitet dovode do odbijanja; fajl može imati najviše 8 KiB i sadržati najviše 16 oblika. Boju, debljinu crte i veličinu postavlja Skava, pa ikona ne može da se maskira kao kontrola. Radite na mreži 24x24.

Bez icon ostaje oznaka po podrazumevanom.

Povratna funkcija: prijava kasnijih stanja

Poziv sadrži callback_url i callback_token. Koristite ih da biste kasnije prijavili nova stanja:

POST <callback_url> sa Authorization: Bearer <callback_token> i Content-Type: application/json, telo najviše 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Pored kartice postoje tri opciona vrednosti:

  • seq: vaš sopstveni brojač. Izveštaj sa manjom ili jednakom vrednošću se odbacuje, pa dva izveštaja ne mogu da se preteknu. Bez seq važi poslednji stigao.
  • final: zatvara interakciju. Token postaje nevažeći i više se ne prikazuju kartice. Dozvoljeno je i u prvom odgovoru, za tokove bez nastavka.
  • 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 toga, kartica je potpuno normalna poruka.

Svaki izveštaj postaje svoja kartica u čatu, prethodna ostaje. Tako je čitljivo koje stanje je prijavljeno. Iz toga sledi preporuka: šaljite samo ono što se promenilo. Kartica koja četvrti put ponavlja broj narudžbine, stavke i ukupno je samo šum za čitaoca.

Dva ograničenja: isti izveštaj dva puta ne pravi drugu karticu, a interakcija može objaviti najviše 50 kartica. Interakcija prihvata izveštaje tokom 90 dana.

Odgovori na koje treba da reagujete

  • 200 uz {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Pročitajte uputstva: oni govore šta je skraćeno ili izbačeno.
  • 401: pogrešan token ili ID interakcije. Ne ponavljajte zahtev.
  • 410: interakcija je zatvorena ili istekla. Ne ponavljajte zahtev.
  • 422: kartica nije upotrebljiva, uz hints kao razlog. Prvo je ispravite.
  • 400 oštećen JSON, 413 preveliko, 429 previše zahteva (ponovite sa pauzom), 500 naša greška, pokušajte kasnije.

Primer 1: narudžbina sa istorijatom statusa

Korak 1, zahtev ka vašem backendu:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Korak 2, vaš odmah odgovor:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

U čatu se sada prikazuje kartica sa ikonom paketa, statusom i unosima korisnika.

Korak 3, kasnije pri odabiru:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Tiha druga kartica bez polja: promenjen je samo status.

Korak 4, pri slanju:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Ova kartica verovatno neko probudi, zato nema notify: false.

Korak 5, pri isporuci:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Kada se koristi final, interakcija se zatvara i token više ne važi.

Primer 2: akcija bez nastavka

Nije svaki tok podataka istorijski. Element sa jednim poljem koji prenosi podatke u vaš sistem zahteva samo jedan odgovor:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Ovde je bitno final: true: u suprotnom bi interakcija ostala otvorena 90 dana sa važećim tokenom, iako više nikada nećete prijavljivati ništa.

Izbor proizvoda iz kataloga

Kada preduzeće učitava svoj katalog artikala, element može da sadrži blok izbor proizvoda. Korisnik iz njega sastavlja korpu, a vi je primate kao listu pod ključem koji je odabrao onaj ko je izgradio element:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Pošto je ključ slobodan, tražite prvu listu koja ima ovaj oblik, a ne fiksno ime. Pre slanja, Skava proverava da li svaki broj zaista postoji u katalogu tog preduzeća, najviše 50 stavki. U kartici se stavke prikazuju kao lista sa slikom proizvoda, nazivom i količinom.

Testiranje

  • Ping u uređivaču elemenata šalje čisti HEAD zahtev bez tokena i bez podataka. Odgovorite bilo čime; bilo koji HTTP odgovor se računa kao dostupan.
  • Testni zahtev pokreće stvarni poziv sa primerom vrednosti, čak i dok je element još uvek u nacrtu, i prikazuje zahtev, odgovor i poruke validatora kartice.
  • Pregled u tabu pored: nalepite JSON odgovor, proverite i vidite gotu karticu uz uputstva. Provera se vrši na serveru istim kodom kao u produkciji.
  • Primer servera: kompletan primer dobavljača radi na api.skava.io i koristi sve što je opisano iznad. Izvorni kod se nalazi u repozitorijumu u example_order_server/, oko 600 redova čistog standardnog biblioteke, namenjen za kopiranje.

Šta još treba da znate

  • Kartica je potpuno obična poruka u četu. Prikazuje se u pretrazi, može se citirati i ostaje u istoriji.
  • Šalje je sistemski pošiljalac, a ne nalog vaše kompanije. I dalje se prikazuje na strani onoga ko je pokrenuo element, a u naslovu je navedeno čiji sistem piše.
  • Ko može da ga pokreće definiše se na elementu: samo članovi firme ili i spoljni korisnici koji dele chat sa njim. Kada vaša firma napusti chat, dozvola automatski ističe.
  • API element sa isteklim tokenom je u stanju mirovanja: trenutne aplikacije ga sakrivaju u meniju, a poziv koji se ipak pošalje odbija se na serveru. Administrator čuva novi token za njega, što takođe funkcioniše na oslobođenom interfejsu.

Povezano

Kreiranje i oslobađanje: Custom Elements: API interfejsi. Popunljivi dokumenti umesto interfejsa: Custom Elements: Dokumenti.