Skava Skava / Wiki

Povezivanje prilagođenih elemenata za programere

Ova stranica namijenjena je programerima koji povezuju pozadinski sustav tvrtke sa Skavom. Kako se stvara i objavljuje API element opisano je na stranici Prilagođeni elementi: API sučelja; ovdje pokrivamo sve što se mora dogoditi na drugom kraju linije.

Ideja u jednoj rečenici: Skava ne poznaje vašu domenu. Poznaje točno jedan format, a to je kartica. Vi odlučujete što piše na njoj, mi provjeravamo samo oblik, veličinu i sigurnost. Narudžba materijala je jedan primjer; sljedeća tvrtka prikuplja povratne informacije korisnika, a ona nakon te arhivira fotografiju gradilišta u svojim zapisima.

Pregled procesa

  1. Administrator tvrtke stvara API element u Skavi: obrazac te adresu, metodu i token vašeg pozadinskog sustava.
  2. Netko u chatu popuni obrazac i pošalje ga.
  3. Skava poziva vaš backend i šalje popunjene vrijednosti kao JSON.
  4. Vaš odgovor postaje kartica u chatu.
  5. Po želji kasnije prijavljujete nova stanja putem callbacka. Svaka prijava postaje nova kartica, a prethodna ostaje.

Zahtjevi za vaš backend

  • HTTPS. Samo https://, bez http, bez podataka za prijavu u adresi, najviše 2000 znakova.
  • Javno dostupno. Dostavljač mora se rješavati isključivo na javne IP adrese. Lokalni host, privatne mreže, link-local i cloud metapodaci se odbacuju, a to se provjerava pri svakom pozivu.
  • Fiksna adresa. Skava rješava dostavljača jednom i fiksira vezu na tu IP adresu. Promjena DNS-a tijekom poziva nema utjecaja.
  • Bez preusmjeravanja. Preusmjeravanje 301 na "ispravnu" adresu računa se kao neuspjeh. Unesite konačnu adresu odmah.
  • Vrijeme odgovora. Vrijeme isteka je podešivo po elementu i ograničeno na 30 sekundi. Ako trebate duže, odgovorite odmah i prijavite rezultat kasnije putem povratnog poziva.
  • Veličina odgovora. Skava čita najviše 256 KiB.
  • Content-Type. Tijelo se parsira samo ako je application/json.

Zahtjev koji stiže do vas

Metoda je GET, POST, PUT ili PATCH, ovisno o elementu. Kod POST, PUT i PATCH vrijednosti stižu kao JSON tijelo, a kod GET kao parametri upita.

Autentifikacija je jedan zaglavlje čije se ime i prefiks vrijednosti konfiguriraju u elementu, obično Authorization s prefiksom Bearer . Token se pohranjuje šifrirano na našoj strani. Zaglavlja host, content-length, content-type, cookie i accept-encoding ne mogu se postaviti.

Tijelo je ravan objekt. Ključeve odabire on tko je izgradio element; ugniježđavanje se pojavljuje samo tamo gdje su dodali tablicu ili odabirač 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 uvijek dolaze od nas, pa ih ne koristite sami:

  • locale: jezični kod korisnika. Odgovorite na tom jeziku; mi ne prevodimo vaše tekstove.
  • callback_url i callback_token: povratni poziv za ovo jedno interakcijsko događanje, vidi dolje. Prisutni su samo kada poziv dolazi iz chata.

Polja konteksta, kao što su ime, tvrtka, projekt ili podrazgovor, popunjava sam poslužitelj, izvedena iz kanala u kojem je element pokrenut. Klijent s izmjenama ne može tamo navesti drugo ime projekta.

Odgovor: format kartice

Odgovori s 2xx i objektom card. To je točno ono što postaje kartica u chatu:

{"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): cijeli broj 1. Kao tekst ("1") odbija se. Bez njega odgovor se ne računa kao kartica i primjenjuje se mapiranje odgovora konfigurirano u elementu.
  • title: naslov kartice.
  • state: samo boja i ton ikone, jedan od ok, pending, warn, error. Nepoznata vrijednost vraća se na ok i dobivaš napomenu.
  • status_text: slobodni tekst koji ne tumačimo. Nalazi se na vrhu kartice i prikazuje se u popisu chatova te u push obavijestima.
  • fields: popis label i value. Najviše 20 stavki, label 80 znakova, value 200, title i status_text po 120. Vrijednosti koje su predugе se skraćuju, a ne odbacuju: narudžba ne smije propasti zbog sitnice.
  • icon: vidi dolje.

Što Skava radi s vašim tekstovima prije nego što stignu u chat: preslici i kontrolni znakovi se uklanjaju (znak za pisanje s desna na lijevo inače bi mogao obrnuti prikaz iznosa), backtickovi se zamjenjuju, a sve što počinje s [SKAVA: se neutralizira. Posljednje sprječava da se vrijednost kartice čita kao neki drugi chat element, na primjer kao zahtjev za plaćanje.

Linkovi u poljima, HTML i slike se ne mogu postaviti. Chat je povjerljivo okruženje, a klikabilna adresa iz stranog backend sustava bila bi pozivnica za ponovno izgradnju prijavne stranice.

Unosi korisnika pripadaju poslužitelju: pojavljuju se na prvoj kartici i ne možete ih prepisati. U chatu predstavljaju zapis onoga što je stvarno poslano.

Ikone

Koristeći icon, kartica dobiva vlastiti 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 vlastiti SVG kao niz znakova. Iz njega Skava uzima samo geometriju (path, circle, ellipse, rect, line, polyline, polygon s njihovim numeričkim atributima) i gradi vlastitu sliku. Skripte, stilovi, vanjske reference, foreignObject i atributi događaja se odbacuju; doctype ili entitet dovode do odbijanja; datoteka može imati najviše 8 KiB i sadržavati najviše 16 oblika. Boju, debljinu crte i veličinu postavlja Skava, pa ikona ne može imitirati kontrolu. Radite na mreži 24 x 24.

Bez icon ostaje oznaka po zadanoj.

Povratna funkcija: prijava kasnijih stanja

Poziv sadrži callback_url i callback_token. Koristite ih za prijavu novih stanja kasnije:

POST <callback_url> s Authorization: Bearer <callback_token> i Content-Type: application/json, tijelo 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}

Osim kartice, postoje tri opcionalne vrijednosti:

  • seq: vlastiti brojač. Izvještaj s manjom ili jednakom vrijednošću se odbacuje, pa dva izvještaja ne mogu međusobno preteći. Bez seq vrijedi onaj koji stigne zadnji.
  • 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 se kartica objavi tiho, bez broja nepročitanih i bez obavijesti. Za međukorake koji ne bi trebali buditi nikoga. Bez toga, kartica je potpuno normalna poruka.

Svaki izvještaj postaje svoja kartica u chatu, prethodna ostaje. Tako je čitljivo koje je stanje prijavljeno. Iz toga slijedi preporuka: šaljte samo ono što se promijenilo. Kartica koja četvrti put ponavlja broj narudžbe, stavke i zbroj je samo šum za čitatelja.

Dva ograničenja: isti izvještaj dvaput ne stvara drugu karticu, a interakcija može objaviti najviše 50 kartica. Interakcija prihvaća izvještaje 90 dana.

Odgovori na koje trebaš reagirati

  • 200 s {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Pročitaj upute: one govore što je skraćeno ili izbačeno.
  • 401: pogrešan token ili ID interakcije. Ne ponavljaj.
  • 410: interakcija je zatvorena ili istekla. Ne ponavljaj.
  • 422: kartica nije upotrebljiva, uz hints kao razlog. Prvo to ispravi.
  • 400 neispravan JSON, 413 preveliko, 429 prevelik broj zahtjeva (ponovite s odmakom), 500 naša greška, pokušajte kasnije.

Primjer 1: narudžba s poviješću statusa

Korak 1, zahtjev prema 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"}]}}

Razgovor sada prikazuje karticu s 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: promijenio se 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 vjerojatno će probuditi nekoga, 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}

S final interakcija je zatvorena i token više ne radi.

Primjer 2: akcija bez nastavka

Nije svaki tok povijest. Element s jednim poljem koji prenosi nešto u vaš sustav zahtijeva 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}

Ovdje je bitno final: true: inače bi interakcija ostala otvorena 90 dana s valjanim tokenom, iako više nikada nećete prijaviti ništa.

Odabir proizvoda iz kataloga

Nakon što tvrtka učitava svoj katalog artikala, element može sadržavati blok odabira proizvoda. Korisnik iz njega sastavlja košaricu, a vi je primate kao popis pod ključem koji je odabrao on tko je izgradio element:

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

Budući da je ključ slobodan, tražite prvi popis koji ima ovaj oblik, a ne fiksno ime. Prije slanja, Skava provjerava postoji li svaki broj stvarno u katalogu te tvrtke, najviše 50 stavki. U kartici se stavke prikazuju kao popis s slikom proizvoda, nazivom i količinom.

Testiranje

  • Ping u uređivaču elemenata šalje gol HEAD zahtjev bez tokena i podataka. Odgovorite bilo čime; bilo koji HTTP odgovor se računa kao dostupan.
  • Testni zahtjev pokreće stvarni poziv s uzorkom vrijednosti, čak i dok je element još u nacrtu, te prikazuje zahtjev, odgovor i poruke validatora kartice.
  • Pregled u kartici pored: zalijepite svoj odgovor u JSON formatu, provjerite i vidite gotovu karticu uz upute. Provjerava se na poslužitelju istim kodom kao u produkciji.
  • Primjer poslužitelja: kompletan primjer dobavljača radi na api.skava.io i koristi sve što je opisano gore. Njegov izvor se nalazi u repozitoriju pod example_order_server/, oko 600 redova čistog standardnog biblioteke, namijenjen za kopiranje.

Što još trebate znati

  • Kartica je potpuno obična poruka u chatu. Pojavljuje se u pretrazi, može se citirati i ostaje u povijesti.
  • Šalje je sustavni pošiljatelj, a ne račun tvrtke. I dalje se prikazuje na strani osobe koja je pokrenula element, a u naslovu je navedeno čiji je sustav piše.
  • Tko ga smije pokretati definirano je na elementu: samo članovi tvrtke ili i vanjske osobe koje dijele chat s njim. Kada vaša tvrtka napusti chat, dopuštenje automatski istječe.
  • API element s isteklim tokenom je u mirovanju: trenutne aplikacije skrivaju ga u izborniku, a poziv poslan unatoč tome odbijen je na poslužitelju. Administrator sprema novi token za njega, što radi i na objavljenom sučelju.

Povezano

Kreiranje i objavljivanje: Prilagođeni elementi: API sučelja. Ispunjive dokumente umjesto sučelja: Prilagođeni elementi: Dokumenti.