Ova stranica namijenjena je programerima koji povezuju backend tvrtke s Skavom. Kako se stvara i objavljuje API element objašnjeno je na stranici Prilagođeni elementi: sučelja API-ja; ovdje obrađujemo sve što se mora dogoditi na drugom kraju veze.

Ideja u jednoj rečenici: Skava ne poznaje vašu domenu. Poznat joj je točno jedan format, 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 toga arhivira fotografiju gradilišta u svojim zapisima.

Pregled tijeka

1. Administrator tvrtke stvara API element u Skavi: obrazac te adresu, metodu i token vašeg backend sustava.
2. Netko u chatu popuni obrazac i pošalje ga.
3. Skava poziva vaš backend i šalje ispunjene vrijednosti kao JSON.
4. Vaš odgovor postaje karta u chatu.
5. Opcionalno, kasnije možete prijaviti nova stanja putem callbacka. Svako prijavljivanje postaje nova karta; prethodna ostaje.

Zahtjevi za vaš backend

• HTTPS. Samo https://, bez http, bez vjerodajnica u adresi, najviše 2000 znakova.
• Javno dostupno. Host mora biti isključivo javna IP adresa. Localhost, privatne mreže, link-local i cloud metapodaci se odbacuju, a to se provjerava pri svakom pozivu.
• Fiksna adresa. Skava rješava host jednom i fiksira vezu na tu IP adresu. Promjena DNS-a tijekom poziva nema učinka.
• Bez preusmjeravanja. Preusmjeravanje 301 na "ispravnu" adresu smatra se neuspjehom. Unesite konačnu adresu odmah.
• Vrijeme odgovora. Vrijeme isteka je konfigurabilno po elementu i strogo ograničeno na 30 sekundi. Ako trebate duže vrijeme, odgovorite odmah i prijavite rezultat kasnije putem povratnog poziva.
• Veličina odgovora. Skava čita najviše 256 KiB.
• Vrsta sadržaja. Tijelo se analizira samo s application/json.

Zahtjev koji stiže do vas

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

Autentifikacija je jedna zaglavlja čije se ime i prefiks vrijednosti konfiguriraju u elementu, obično Authorization s prefiksom Bearer . Token je šifriran spremljen 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 onaj tko je izgradio element; ugniježđivanje se pojavljuje samo tamo gdje su dodali tablicu ili odabir 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 nemojte sami koristiti:

• locale: jezični kod korisnika. Odgovorite na tom jeziku; mi ne prevodimo vaše tekstove.
• callback_url i callback_token: povratni poziv za ovu interakciju, vidite dolje. Prisutni su samo kada poziv dolazi iz chata.

Polja konteksta poput name, company, project ili subchat popunjava sam server, izvedena iz kanala u kojem je element pokrenut. Promijenjeni klijent ne može tamo tvrditi drugo ime projekta.

Odgovor: format kartice

Odgovorite s 2xx i objektom card. Točno 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") odbijen je. Bez njega odgovor se ne računa kao kartica i primjenjuje se preslikavanje odgovora konfigurirano u elementu.
• title: naslov kartice.
• state: samo boja i ton ikone, jedna od vrijednosti ok, pending, warn, error. Nepoznata vrijednost vraća se na ok i dobivate uputu.
• status_text: slobodan tekst koji ne tumačimo. Nalazi se na vrhu kartice i to je ono što se prikazuje u popisu chatova i u guranom obavijesti.
• polja: popis label i value. Najviše 20 stavki, label 80 znakova, value 200, title i status_text po 120. Preduge vrijednosti se skraćuju, a ne odbacuju: narudžba ne smije propasti zbog detalja.
• ikonica: vidi dolje.

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

Linkovi u poljima, HTML i slike se ne mogu postaviti. Chat je okruženje koje uživa povjerenje, a klikabilna adresa s vanjskog backend sustava bila bi poziv na izradu stranice za prijavu.

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

Ikone

S icon kartica dobiva vlastiti znak u zaglavlju. Dva načina:

Ime iz priloženog seta: 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. Skava iz njega 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 dovodi do odbacivanja; datoteka može biti najviše 8 KiB i sadržavati najviše 16 oblika. Boju, debljinu crte i veličinu postavlja Skava, pa se ikona ne može pretvoriti u kontrolu. Radite s mrežom 24 x 24.

Bez icon ostaje zadani znak.

Povratni poziv: 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: vaš vlastiti brojilo. Izvješće s manjom ili jednakom vrijednošću odbacuje se kako dva izvješća ne bi mogla preteći jedno drugo. Bez seq vrijedi posljednje stiglo.
• final: završava interakciju. Token postaje nevažeći i više se ne pojavljuju nove kartice. Dopušteno je i u prvom odgovoru za tokove bez daljnjih pitanja.
• notify: postavite na false da se kartica objavi tiho, bez broja nepročitanih poruka i bez obavijesti. Namijenjeno međukoracima koji ne bi trebali probuditi nikoga. Bez ove postavke, kartica je potpuno normalna poruka.

Svako izvješće postaje svojom karticom u chatu, a prethodno ostaje. Tako je jasno koje je stanje prijavljeno. Iz toga proizlazi preporuka: šaljte samo ono što se promijenilo. Kartica koja četvrti put ponavlja broj narudžbe, stavke i ukupni iznos samo je šum za čitatelja.

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

Odgovori na koje trebate reagirati

• 200 s {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Pročitajte upute: one kažu što je skraćeno ili izostavljeno.
• 401: krivi token ili ID interakcije. Ne pokušavajte ponovno.
• 410: interakcija zatvorena ili istekla. Ne pokušavajte ponovno.
• 422: kartica neupotrebljiva, s hints kao razlogom. Prvo je popravite.
• 400 neispravan JSON, 413 preveliko, 429 previše zahtjeva (ponovite s pauzom), 500 naša greška, pokušajte kasnije.

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

Korak 1, zahtjev vašem backend sustavu:

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š trenutni 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"}]}}

Chat sada prikazuje karticu s ikonom paketa, statusom i unosima korisnika.

Korak 3, kasnije tijekom pakiranja:

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: promijenjen je samo status.

Korak 4, pri otpremi:

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 može probuditi nekoga, stoga 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 funkcionira.

Primjer 2: radnja bez nastavka

Niti jedan tijek nema povijest. Element s jednim poljem koji nešto proslijeđuje vašem sustavu 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 se više nikada ništa neće prijavljivati.

Odabir proizvoda iz kataloga

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

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

Budući da je ključ besplatan, potražite prvi popis koji ima ovaj oblik, a ne fiksni naziv. Prije slanja, Skava provjerava postoji li svaki broj 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 bez podataka. Odgovorite bilo čime; bilo koji HTTP odgovor znači da je dostupan.
• Testni zahtjev pokreće stvarni poziv s uzorkovanim vrijednostima, čak i dok je element još u nacrtu, te prikazuje zahtjev, odgovor i poruke validatora kartice.
• Pregled na kartici do njega: zalijepite svoj odgovor u JSON formatu, provjerite i vidjet ćete gotovu karticu uz upute. Provjera se vrši na poslužitelju istim kodom kao u produkciji.
• Primjer poslužitelja: kompletan primjer dobavljača radi na api.skava.io i koristi sve gore opisano. Izvorni kod nalazi se u spremištu pod example_order_server/, oko 600 redaka čiste standardne biblioteke, namijenjen za kopiranje.

Što još trebate znati

• Kartica je potpuno normalna poruka u chatu. Pojavljuje se u pretraživanju, može se citirati i ostaje u povijesti.
• Slanja je sustavni pošiljatelj, a ne račun vaše tvrtke. I dalje se pojavljuje na strani onoga tko je pokrenuo element, a u naslovu je navedeno čiji sustav piše.
• Tko ga može pokrenuti, postavljeno je na elementu: samo članovi tvrtke ili i vanjske osobe koje dijele chat s njom. Kada vaša tvrtka napusti chat, dopuštenje se automatski prestaje.
• API element s isteklim tokenom je neaktivan i ne pojavljuje se u izborniku dok administrator ne spremi novi.

Povezano

Stvaranje i objavljivanje: Prilagođeni elementi: sučelja API-ja. Popunjivi dokumenti umjesto sučelja: Prilagođeni elementi: dokumenti.