Ta stran je namenjena razvijalcem, ki povezujejo backend podjetja s Skavo. Postopek ustvarjanja in objave API elementa je obravnan na strani Custom Elements: API vmesniki; tukaj pa zajamemo vse, kar se mora zgoditi na drugi strani povezave.

Ideja v enem stavku: Skava ne pozna vašega področja. Pozna natanko en format, in sicer kartico. Vi odločite, kaj piše na njej, mi pa preverimo le obliko, velikost in varnost. Naročilo materiala je en primer; naslednje podjetje zbira povratne informacije uporabnikov, tisto po njem pa v svoje evidence shrani fotografijo gradbišča.

Pregled poteka

1. Upravitelj podjetja v Skavi ustvari API element: obrazec ter naslov, metodo in žeton vašega backenda.
2. Nekdo v klepetu izpolni obrazec in ga pošlje.
3. Skava pokliče vaš backend in pošlje izpolnjene vrednosti kot JSON.
4. Vaš odgovor postane kartica v klepetu.
5. Po želji lahko kasneje poročate o novih stanjih prek callbacka. Vsako poročilo postane nova kartica; prejšnja ostane.

Zahteve za vaš backend

• HTTPS. Samo https://, brez http, brez poverilnic v naslovu, največ 2000 znakov.
• Javno dostopno. Gostitelj se mora razrešiti izključno na javne IP naslove. Lokalni gostitelj, zasebna omrežja, povezave na lokalni vmesnik in metapodatki o oblaku so zavrnjeni; to se preveri pri vsakem klicu.
• Fiksni naslov. Skava gostitelja razreši enkrat in povezavo določi na ta IP naslov. Sprememba DNS med klicem nima učinka.
• Brez preusmeritev. Preusmeritev 301 na »pravilen« naslov se šteje za napako. Vnesite končni naslov takoj.
• Čas odziva. Časovni limit je prilagodljiv za vsak element in trdno omejen na 30 sekund. Če potrebujete daljši čas, takoj odgovorite in rezultat kasneje sporočite prek povratnega klica.
• Velikost odziva. Skava prebere največ 256 KiB.
• Content-Type. Telo se razlaga le s application/json.

Zahteva, ki pride do vas

Metoda je GET, POST, PUT ali PATCH, odvisno od elementa. Pri POST, PUT in PATCH vrednosti pridejo kot JSON telo, pri GET pa kot parametri poizvedbe.

Overjanje je ena glava, katere ime in predpona vrednosti sta konfigurirani v elementu, običajno Authorization s predpono Bearer . Žeton je na naši strani shranjen šifriran. Glav host, content-length, content-type, cookie in accept-encoding ni mogoče nastaviti.

Telo je raven objekt. Ključe izbere tisti, ki je zgradil element; gnezdenje se pojavi le tam, kjer so dodali tabelo ali izbiralnik izdelka:

{"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či vedno prihajajo od nas, zato jih ne uporabljajte sami:

• locale: jezikovna oznaka uporabnika. Odgovorite v tem jeziku; vaših besedil ne prevajamo.
• callback_url in callback_token: povratni klic za to eno interakcijo, glejte spodaj. Prisotna sta le, ko klic prihaja iz klepeta.

Polja konteksta, kot so ime, podjetje, projekt ali podklepet, napolni sam strežnik na podlagi kanala, v katerem je bil element zagnan. Spremenjeni odjemalec se tam ne more izrekati za drugo ime projekta.

Odgovor: format kartice

Odgovorite s 2xx in objektom card. Točno to postane kartica v klepetu:

{"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 (obvezno): celo število 1. Kot besedilo ("1") je zavrnjeno. Brez tega odgovor ne šteje kot kartica in velja preslikava odgovora, konfigurirana v elementu.
• title: naslov kartice.
• state: le barva in odtenik ikone, eno od ok, pending, warn, error. Neznana vrednost se povrne na ok in prejmete opozorilo.
• status_text: prost besedilni zapis, ki ga ne razlagamo. Nahaja se na vrhu kartice in se prikaže tudi v seznamu klepetov ter v obvestilu.
• polja: seznam label in value. Največ 20 vnosov, label 80 znakov, value 200, title in status_text po 120. Pre dolge vrednosti se skrajšajo, ne zavrnejo: naročilo ne sme odpovedati zaradi podrobnosti.
• ikonica: glej spodaj.

Kaj Skava stori z vašimi besedili, preden pridejo v pogovor: presledki vrstic in nadzorni znaki se odstranijo (znak z desne na levo bi sicer lahko obrnil prikaz zneska), backticki se zamenjajo, vse, kar se začne z [SKAVA:, pa se nevtralizira. Zadnje prepreči, da bi se vrednost kartice brala kot drug element pogovora, na primer zahteva za plačilo.

Povezav v poljih, HTML in slikah ni mogoče nastaviti. Pogovor je zaupanja vredno okolje, klikljivi naslov iz tujega strežnika pa bi bil povabilo k ponovni izdelavi strani za prijavo.

Vnosi uporabnika pripadajo strežniku: pojavijo se na prvi kartici in jih ne morete prepisati. V pogovoru so zapis o tem, kar je dejansko oddano.

Ikone

Z icon dobi kartica v glavi lastno oznako. Dve možnosti:

Ime iz priloženega nabora: 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.

Ali vaš lastni SVG kot niz. Skava iz njega vzame le geometrijo (path, circle, ellipse, rect, line, polyline, polygon z njihovimi numeričnimi atributi) in zgradi lastno sliko. Skripte, stile, zunanje reference, foreignObject in dogodkovne atribute zavrne; datoteka ne sme vsebovati doctype ali entitet, ne sme biti večja od 8 KiB in vsebovati več kot 16 oblik. Barvo, debelino črte in velikost določi Skava, zato se ikona ne more prikazati kot nadzorni element. Delajte na mreži 24 x 24.

Brez icon ostane privzeta oznaka.

Povratni klic: poročanje o kasnejših stanjih

Klic vsebuje callback_url in callback_token. Uporabite ju za kasnejše poročanje o novih stanjih:

POST <callback_url> z Authorization: Bearer <callback_token> in Content-Type: application/json, telo največ 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}

Poleg kartice obstajajo trije izbirni parametri:

• seq: vaš lastni števec. Poročilo z manjšo ali enako vrednostjo se zavrne, da se dva poročila ne moreta prehiteti. Brez seq velja zadnje prispelo poročilo.
• final: zaključi interakcijo. Žeton postane neveljaven in ne pojavijo se več kartice. Dovoljeno je tudi v prvem odgovoru za tokove brez nadaljnjih vprašanj.
• notify: nastavite na false, da se kartica objavi tiho, brez števila neprebranih sporočil in brez obvestila. Primerno za vmesne korake, ki ne bi smeli prebuditi nikogar. Brez tega je kartica povsem običajno sporočilo.

Poročilo postane svoja kartica v klepetu, prejšnja ostane. Tako je razvidno, katero stanje je bilo poročeno. Iz tega izhaja priporočilo: pošljite le, kar se je spremenilo. Kartica, ki ponavlja številko naročila, postavke in skupni znesek že četrtič, je za bralca le šum.

Dve omejitvi: isto poročilo dvakrat ne ustvari druge kartice, interakcija pa lahko objavi največ 50 kartic. Interakcija sprejema poročila 90 dni.

Odgovori, na katere morate reagirati

• 200 z {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Preberite namige: povedo, kaj je bilo skrajšano ali izpuščeno.
• 401: napačen žeton ali ID interakcije. Ne poskušajte ponovno.
• 410: interakcija je zaprta ali potekla. Ne poskušajte ponovno.
• 422: kartica ni uporabna, z namigi kot razlogom. Najprej jo popravite.
• 400 poškodovan JSON, 413 prevelik, 429 preveč zahtev (ponovite z zamikom), 500 naša napaka, poskusite kasneje.

Primer 1: naročilo s kronologijo stanj

Korak 1, zahteva do vašega strežnika:

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

V klepetu se zdaj prikaže kartica z ikono paketa, stanjem in vnosom uporabnika.

Korak 3, kasneje med pripravo:

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 brez polj: spremenil se je le status.

4. korak, pri pošiljanju:

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}

Ta kartica lahko koga prebudi, zato ni notify: false.

5. korak, pri dostavi:

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

Z final je interakcija zaključena in žeton ne deluje več.

Primer 2: dejanje brez nadaljnjih korakov

Nekateri tokovi nimajo zgodovine. Element z enim samim poljem, ki nekaj predloži vašemu sistemu, potrebuje le en odgovor:

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

Tukaj je pomembna nastavitev final: true: sicer bi interakcija ostala odprta 90 dni z veljavnim žetonom, čeprav ne boste nikoli več poročali o ničemer.

Izbirnik izdelkov iz kataloga

Ko podjetje naloži svoj katalog izdelkov, element lahko vsebuje blok izbirnik izdelkov. Uporabnik iz njega sestavi košarico, vi pa jo prejmete kot seznam pod ključem, ki ga je izbral tisti, ki je element ustvaril:

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

Ker je ključ brezplačen, poiščite prvi seznam s to obliko, ne pa fiksnega imena. Pred pošiljanjem Skava preveri, ali vsa števila res obstajajo v katalogu tega podjetja, največ 50 postavk. V kartici se postavke prikažejo kot seznam s sliko izdelka, imenom in količino.

Testiranje

• Ping v urejevalniku elementa pošlje gol HEAD brez žetona in brez podatkov. Odgovorite s čim koli; vsak HTTP odziv šteje kot dosegljiv.
• Testni zahtevek sproži pravi klic z vzorčnimi vrednostmi, tudi če je element še v osnutku, in prikaže zahtevek, odziv ter sporočila preverjalnika kartice.
• Predogled na zavihku ob njem: prilepite svoj odzivni JSON, preverite in videli boste končano kartico s pripomočki. Preverjeno je na strežniku z isto kodo kot v proizvodnem okolju.
• Primer strežnika: popoln primer dobavitelja deluje na api.skava.io in uporablja vse zgoraj opisano. Njegov izvorna koda je v repozitoriju pod example_order_server/, približno 600 vrstic čiste standardne knjižnice, namenjene za kopiranje.

Kaj še morate vedeti

• Kartica je popolnoma navadno sporočilo v klepetu. Pojavlja se v iskanju, jo je mogoče citirati in ostane v zgodovini.
• Pošlje jo sistemski pošiljatelj, ne račun vaše družbe. Vendar se pojavi na strani tistega, ki je izvedel element, v naslovu pa je navedeno, kateri sistem piše.
• Kdo ga sme izvesti, je določeno na elementu: le člani družbe ali tudi zunanje osebe, ki delijo klepet z njim. Ko vaša družba zapusti klepet, se dovoljenje samodejno prekliče.
• API element z poteklim žetonom je neaktiven in se v meniju ne prikaže, dokler skrbnik ne shrani novega.

Povezano

Ustvarjanje in objava: Prilagojeni elementi: vmesniki API. Polnilni dokumenti namesto vmesnikov: Prilagojeni elementi: dokumenti.