Skava Skava / Wiki

Povezovanje prilagodljivih elementov za razvijalce

Ta stran je namenjena razvijalcem, ki povezujejo backend podjetja s Skavo. Postopek ustvarjanja in objave API elementa je obravnavan na strani Prilagodljivi elementi: API vmesniki; tukaj obravnavamo 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 bo zapisano, mi pa preverimo le obliko, velikost in varnost. Naročilo materiala je en primer; naslednje podjetje zbiralo povratne informacije uporabnikov, to pa arhiviralo fotografije gradbišča v lastne zabeleške.

Pregled postopka

  1. Skupni administrator podjetja ustvari API element v Skavi: obrazec ter naslov, metoda 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 kasneje poročate o novih stanjih prek callback. Vsako poročilo postane nova kartica; prejšnja ostane.

Zahteve za vaš backend

  • HTTPS. Samo https://, brez http, brez poverilnih podatkov v naslovu, največ 2000 znakov.
  • Javno dostopno. Gostitelj se mora razrešiti izključno na javne IP naslove. Lokalni gostitelj, zasebna omrežja, povezava na lokalni ravni in metapodatki v oblaku so zavrnjeni, kar se preverja pri vsakem klicu.
  • Fiksni naslov. Skava gostitelja razreši enkrat in povezavo pripne na ta IP. Sprememba DNS med klicem nima učinka.
  • Brez preusmeritev. Preusmeritev 301 na "pravilen" naslov se šteje kot neuspeh. Vnesite končni naslov takoj.
  • Čas odziva. Časovna omejitev je nastavljiva za vsak element in trdno omejena na 30 sekund. Če potrebujete daljši čas, odgovorite takoj in rezultat poročite kasneje prek povratnega klica.
  • Velikost odgovora. Skava prebere največ 256 KiB.
  • Content-Type. Vsebina se razčleni le, če je application/json.

Zahteva, ki prispe do vas

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

Overitev poteka prek enega glave, katerega ime in predpona vrednosti sta nastavljena v elementu, običajno Authorization s predpono Bearer . Žeton je shranjen šifrirano na naši strani. Glav host, content-length, content-type, cookie in accept-encoding ni mogoče nastaviti.

Telo je enostavno predmet. Ključe izbere tisti, ki je element zgradil; gnezdenje se pojavi le tam, kjer so dodali tabelo ali izbirnik 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": "…"}

Trije ključi vedno prihajajo od nas, zato jih ne uporabljajte sami:

  • locale: jezikovna koda uporabnika. Odgovorite v tem jeziku; vaši teksti se ne prevajajo.
  • callback_url in callback_token: povratni klic za to interakcijo, glejte spodaj. Prisotna sta le, kadar klic prihaja iz klepeta.

Polja konteksta, kot so ime, podjetje, projekt ali podklepet, izpolni sam strežnik, izpeljana so iz kanala, v katerem je element bil izveden. Spremenjen odjemalec tam ne more trditi drugega imena projekta.

Odgovor: oblika kartice

Odgovorite s 2xx in objektom card. To je natanko tisto, kar 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") se zavrže. Brez tega odgovor ne šteje kot kartica in se uporabi preslikava odgovora, ki je nastavljena v elementu.
  • title: naslov kartice.
  • state: samo barva in ton ikone, ena od vrednosti ok, pending, warn, error. Neznana vrednost se povrne na ok in dobite opozorilo.
  • status_text: prosti besedilni vnos, ki ga ne razlagamo. Nahaja se na vrhu kartice in se prikaže tudi v seznamu klepetov ter v push obvestilu.
  • fields: seznam parov label in value. Največ 20 vnosov, label 80 znakov, value 200, title in status_text po 120 znakov. Predolge vrednosti se okrajšajo, ne zavržejo: naročilo se ne sme spremeniti zaradi podrobnosti.
  • icon: glej spodaj.

Kaj Skava naredi z vašimi besedili, preden prispejo v klepet: presledki in kontrolni znaki se odstranijo (znak za desno levo bi sicer lahko obrnil prikaz zneska), backticki se zamenjajo, vse, kar se začne z [SKAVA:, se nevtralizira. Zadnje prepreči, da bi se vrednost kartice brala kot drug element klepeta, na primer zahteva za plačilo.

Povezave v poljih, HTML in slike se ne morejo nastaviti. Klepet je zaupanja vredno okolje, klikljivi naslov iz tujega backend sistema bi bil povabilo za ponovno gradnjo prijavnega obrazca.

Vnosi uporabnika pripadajo strežniku: prikazani so na prvi kartici in jih ne morete prekriti. V klepetu predstavljajo zapis o tem, kaj je bilo dejansko oddano.

Ikone

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

Ime iz priložene zbirke: 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 lasten SVG kot niz. Skava iz njega vzame le geometrijo (path, circle, ellipse, rect, line, polyline, polygon z njihovimi številskimi lastnostmi) in sestavi svojo sliko. Skripte, slogi, zunanje reference, foreignObject in lastnosti dogodkov se zavržejo; deklaracija tipa dokumenta ali entiteta povzročita zavržitev; datoteka sme imeti največ 8 KiB in vsebovati največ 16 oblik. Barvo, debelino črte in velikost določi Skava, zato se ikona ne more pretvarjati v 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 neobvezni parametri:

  • seq: vaš lastnik. Poročilo z manjšo ali enako vrednostjo se zavrne, da se dve poročili ne moreta preteči. Brez seq velja zadnje prejet.
  • final: zaključi interakcijo. Žeton postane neveljaven in ne pojavijo se več nove kartice. Dovoljeno je tudi v prvem odgovoru, za tokove brez nadaljnjih korakov.
  • notify: nastavite na false, da se kartica objavi tiho, brez števila neprebranih in brez obvestila. Za vmesne korake, ki ne bi smeli zbuditi nikogar. Brez tega je kartica povsem običajno sporočilo.

Vsak poročilo postane svoja kartica v klepetu, prejšnja ostane. Tako je berljivo, katero stanje je bilo poročeno. Iz tega sledi priporočilo: pošljite le tisto, kar se je spremenilo. Kartica, ki četrtič ponovi številko naročila, postavke in skupno, je le šum za bralca.

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

Odgovori, na katere morate odzvati

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

Primer 1: naročilo z zgodovino statusov

Korak 1, zahteva na 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š takojšnji 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"}]}}

Pogovor zdaj prikaže kartico z ikono paketa, statusom in vnosom uporabnika.

Korak 3, kasneje ob izbiri:

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.

Korak 4, ob 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 morda koga zbudi, zato ni notify: false.

Korak 5, ob 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 se interakcija zaključi in žeton ne deluje več.

Primer 2: dejanje brez nadaljnjih korakov

Ne vsak tok ima zgodovino. Element z enim samim poljem, ki nekaj preda v vaš sistem, potrebuje samo 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 pomembno final: true: sicer bi se interakcija ohranila odprta 90 dni z veljavnim žetonom, čeprav ne boste več ničesar poročali.

Izbira izdelka iz kataloga

Ko podjetje naloži svoj katalog artiklov, lahko element 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 zgradil:

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

Ker je ključ prost, iščite prvi seznam s to obliko, ne pa določenega imena. Pred pošiljanjem Skava preveri, ali vsaka številka res obstaja v katalogu tega podjetja, največ 50 postavk. Na kartici se postavke prikažejo kot seznam s sliko izdelka, imenom in količino.

Testiranje

  • Ping v urejevalniku elementa pošlje goli HEAD brez žetona in brez podatkov. Odgovorite s čim; vsak HTTP odgovor šteje kot dosegljiv.
  • Testni zahtevek sproži pravi klic z vzorčnimi vrednostmi, tudi medtem ko je element še osnutek, in prikaže zahtevek, odgovor ter sporočila preverjalnika kartice.
  • Predogled v zavihku ob strani: prilepite svoj odgovor v obliki JSON, preverite in vidite končno kartico ter namige. Preverjanje poteka na strežniku z isto kodo kot v produkcijskem okolju.
  • Primer strežnika: celoten primer dobavitelja deluje na api.skava.io in uporablja vse, kar je opisano zgoraj. Vir je v repozitoriju v mapi example_order_server/, ima približno 600 vrstic čiste standardne knjižnice in je namenjen kopiranju.

Kaj še morate vedeti

  • Kartica je popolnoma navadno sporočilo v klepetu. Pojavlja se v iskanju, jo lahko citirate in ostane v zgodovini.
  • Pošlje jo pošiljatelj sistema, ne račun vašega podjetja. Vseeno se prikaže na strani osebe, ki je izvedla element, v naslovu pa je navedeno, kateri sistem piše.
  • Kdo ga lahko uporablja, je nastavljeno na elementu: samo člani podjetja ali tudi zunanji sodelavci, ki z njim delijo klepet. Ko vaše podjetje zapusti klepet, se dovoljenje samodejno prekliče.
  • API element s poteklim žetonom je v mirovanju: trenutne aplikacije ga skrijejo v meniju, klic, ki ga vseeno pošljete, pa strežnik zavrne. Skrbnik za element shrani nov žeton, kar deluje tudi na izdanem vmesniku.

Sorodno

Ustvarjanje in izdajanje: Prilagojeni elementi: API vmesniki. Izpolnljivi dokumenti namesto vmesnikov: Prilagojeni elementi: Dokumenti.