Skava Skava / Wiki

Kohandatud elementide ühendamine arendajatele

See leht on mõeldud arendajatele, kes ühendavad ettevõtte tagakülje Skavaga. API elemendi loomine ja avalikustamine on kirjeldatud lehel Kohandatud elemendid: API liidesed; siin käsitleme kõike, mis peab toimuma teisel liini otsas.

Idee ühes lauses: Skava ei tea teie valdkonda. See tunneb täpselt ühte vormingut, kaardi. Te otsustate, mida see ütleb, me kontrollime ainult kuju, suurust ja ohutust. Materjalide tellimine on üks näide; järgmine ettevõte kogub kasutajate tagasisidet, veel järgmine salvestab objekti foto oma arhiivi.

Voo ülevaade

  1. Ettevõtte administraator loob Skavas API elemendi: vorm koos teie tagakülje aadressi, meetodi ja tokeniga.
  2. Keegi vestluses täidab vormi ja saadab selle.
  3. Skava kutsub sinu tagakülge ja saadab täidetud väärtused JSON-ina.
  4. Sinu vastus muutub vestluses kardiks.
  5. Valikuliselt teatad hiljem uuesti olekust kõnetagastuse kaudu. Iga teade muutub uueks kaardiks; eelmine jääb alles.

Nõuded sinu tagaküljele

  • HTTPS. Ainult https://, mitte http, aadressis ei tohi olla sisselogimisandmeid, maksimaalselt 2000 tähemärki.
  • Avalikult ligipääsetav. Host peab lahenduma ainult avalike IP-aadressidega. Kohalik server, privaatvõrgud, link-local ja pilve metaandmed lükatakse tagasi, seda kontrollitakse iga kutsu korral.
  • Kindel aadress. Skava lahendab hosti ühe korda ja fikseerib ühenduse selle IP-aadressiga. DNS-i muudatus kutsu ajal ei mõjuta ühendust.
  • Ümbersuunamisi ei tohi olla. 301 ümbersuunamine "õigele" aadressile loetakse ebaõnnestumiseks. Sisestage lõplik aadress kohe alguses.
  • Vastusaja piir. Aegumisaeg on iga elemendi jaoks seadistatav ja rangelt piiratud 30 sekundiga. Kui vajate rohkem aega, vastake kohe ja esitage tulemus hiljem tagasiside kaudu.
  • Vastuse suurus. Skava loeb maksimaalselt 256 KiB.
  • Content-Type. Keha parsitakse ainult väärtusega application/json.

Päring, mis sulle jõuab

Meetodiks on GET, POST, PUT või PATCH, sõltuvalt elemendist. POST, PUT ja PATCH korral saab väärtused JSON-kehana, GET korral aga päringuparameetritena.

Autentimiseks on üks päis, mille nimi ja väärtuse eesliide on elemendis konfigureeritud, tavaliselt Authorization eesliitega Bearer . Token salvestatakse meie poolt krüpteerituna. Päiseid host, content-length, content-type, cookie ja accept-encoding ei saa määrata.

Keel on lame objekt. Võtmed valib see, kes elemendi loonud; sisestamine ilmub ainult seal, kus on lisatud tabel või tootevalija:

{"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": "…"}

Kolm võtmeväärtust tuleb alati meie poolt, seega ärge kasutage neid ise:

  • locale: kasutaja keelekood. Vastake selles keeles; me ei tõlgi teie tekste.
  • callback_url ja callback_token: tagasiside selle ühe interaktsiooni jaoks, vt allpool. Need on olemas ainult siis, kui kutsu tuleb vestlusest.

Kontekstiväljad nagu nimi, ettevõte, projekt või alamvestlus täidab server ise, tuletatuna kanalist, milles element käivitati. Muudetud klient ei saa seal väita teist projekti nime.

Vastus: kaardi vorming

Vasta koodiga 2xx ja card objektiga. See on täpselt see, mis muutub kaardiks vestluses:

{"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 (kohustuslik): täisarv 1. Tekstina ("1") lükatakse see tagasi. Ilma selleta ei loeta vastust kaardiks ja kehtib elemendis määratletud vastuse kaardistamine.
  • title: kaardi pealkiri.
  • state: ainult värv ja ikooni toon, üks väärtustest ok, pending, warn, error. Tundmatu väärtus asendatakse väärtusega ok ja saate vihje.
  • status_text: vaba tekst, mida me ei tõlgenda. See asub kaardi ülaosas ja kuvatakse ka vestluse nimekirjas ning push-teates.
  • fields: loetelu label ja value paaris. Kuni 20 kirjet, label 80 tähemärki, value 200, title ja status_text igaüks 120. Liiga pikad väärtused lühendatakse, mitte lükatakse tagasi: tellimus ei tohiks üksikasja pärast ebaõnnestuda.
  • icon: vt allpool.

Mida Skava teeb sinu tekstidega enne, kui need vestlusesse jõuavad: ridade vahetused ja juhttähed eemaldatakse (paremalt vasakule kirjutatud täht võiks muidu summa kuvamise pöörata), tagakriipsud asendatakse ja kõik, mis algab [SKAVA: märgiga, neutraliseeritakse. Viimane takistab kaardi väärtuse lugemist mõne teise vestluse elemendina, näiteks maksepalve.

Väljades, HTML-is ja piltides ei saa seada linke. Vestlus on usaldusväärne keskkond ja kliidav aadress võõrast tagaküljest oleks kutsus uuesti sisselogimislehekülge ehitada.

Kasutaja sisestused kuuluvad serverile: need ilmuvad esimesel kaardil ja neid ei saa üle kirjutada. Vestluses on need salvestus tegelikult esitatud andmetest.

Ikoonid

Kaart saab päises oma märgi icon abil. Kaks viisi:

Nimi kaasas olevast hulgist: 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.

Või oma SVG stringina. Skava võtab sellest ainult geomeetria (path, circle, ellipse, rect, line, polyline, polygon koos nende numbriliste atribuutidega) ja loob oma pildi. Skriptid, stiilid, välised viited, foreignObject ja sündmuse atribuudid heidetakse maha; doctype või entiteet viib tagasilükkamiseni; faili suurus võib olla maksimaalselt 8 KiB ja sisaldada maksimaalselt 16 kuju. Värv, joone paksus ja suurus määrab Skava, nii et ikoon ei saa end maskeerida juhtelemendiks. Tööta 24 korda 24 ruudustikuga.

Ilma icon märkusega jääb vaikimisi märge alles.

Tagasiside: hilisemate olekute teavitamine

Kutse sisaldab callback_url ja callback_token. Kasuta neid hilisemate olekute teavitamiseks:

POST <callback_url> päisega Authorization: Bearer <callback_token> ja Content-Type: application/json, keha maksimaalsuurus 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}

Kaardi kõrval on kolm valikulist väärtust:

  • seq: oma loendur. Raport väiksema või võrdse väärtusega heidetakse maha, et kaks raporti ei saaks üksteist ületada. Ilma seq võidab viimane saabuv.
  • final: lõpetab interaktsiooni. Token muutub kehtetuks ja uusi kaarte ei ilmne. Lubatud ka esimeses vastuses, voolude puhul, millel ei ole järelküsimusi.
  • notify: seadke väärtuseks false, et postitada kaart vaikselt, ilma lugemata loendurita ja teavitusteta. Keskvaheprotsesside jaoks, mis ei tohiks kedagi ärata. Ilma selle without, kaart on täiesti tavaline sõnum.

Iga raportist saab oma kaart chatis, eelmine jääb alles. Nii on loetav, milline olek raporteeriti. Sellest tuleneb soovitus: saada ainult muudetud. Kaart, mis kordab neljandal korral tellimuse numbri, tooteid ja kokkuvõtte, on lugejale lihtsalt müra.

Kaks piirangut: sama raport kaks korda ei tekita teist kaarti ja interaktsioon võib postitada maksimaalselt 50 kaarti. Interaktsioon aktsepteerib raporteid 90 päeva.

Vastused, millele peaksid reageerima

  • 200 koos {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Loe vihjed: need ütlevad, mida lühendati või eemaldati.
  • 401: vale token või interaktsiooni id. Ära korda uuesti.
  • 410: interaktsioon on suletud või aegunud. Ära korda uuesti.
  • 422: kaart ei ole kasutatav, põhjuseks hints. Paranda see esmalt.
  • 400 vigane JSON, 413 liiga suur, 429 liiga palju päringuid (korda proovi tagasilükkusega), 500 meie viga, korda proovi hiljem.

Näide 1: tellimus, millel on staatuse ajalugu

Samm 1, päring teie tagasipõhjale:

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"}

Samm 2, teie kohe vastus:

{"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"}]}}

Vestluses kuvatakse nüüd kaart paki ikooniga, staatuse ja kasutaja sisenditega.

Samm 3, hiljem valimisel:

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

Vaikne teine kaart ilma väljadeta: ainult staatus muutus.

Samm 4, saatmisel:

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}

See kaart võib kergitada kellegi, seetõttu ei ole notify: false.

Samm 5, kohaletoimetamisel:

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

final sulgeb interaktsiooni ja token ei ole enam kehtiv.

Näide 2: tegevus ilma järelküsimusteta

Igal voolul pole ajalugu. Element, millel on üks väli ja mis edastab midagi sinu süsteemile, vajab ainult ühte vastust:

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

Siin on oluline final: true: muidu jääb interaktsioon 90 päevaks avatuks kehtiva tokeniga, kuigi sa ei raporteeri enam kunagi midagi.

Tootevalija kataloogist

Pärast ettevõtte artiklite kataloogi üleslaadimist võib element sisaldada tootevalija blokki. Kasutaja koostab sellest ostukorvi ja te saate selle nimekirjana võtmega, mille valis elemendi looja:

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

Kuna võti on vaba, otsige esimest nimekirja, millel on see kuju, mitte kindlat nime. Saatmise eel kontrollib Skava, et iga number oleks selle ettevõtte kataloogis olemas, maksimaalselt 50 toodet. Kaardis kuvatakse tooted nimekirjana koos tootepildiga, nimega ja kogusega.

Testimine

  • Ping elemendi redaktoris saadab puhta HEAD päringu ilma tokenita ja andmeteta. Vastake mis iganes; iga HTTP-vastus loendub saavutatavana.
  • Testipäring teeb päringu näidisväärtustega, isegi kui element on veel mustand, ja kuvab päringu, vastuse ning kaardi valideerija teated.
  • Eelvaade naabrualal: liimige oma vastuse JSON, kontrollige ja näete valmis kaarti koos vihjetega. See kontrollitakse serveril sama koodiga kui tootmises.
  • Näidisserver: täielik näidisvarustaja töötab aadressil api.skava.io ja kasutab kõiki eelnevalt kirjeldatud funktsioone. Selle allikas asub repoo all kaustas example_order_server/, umbes 600 rida puhtat standardraamatukonda, mõeldud kopeerimiseks.

Mida veel teada peaks

  • Kaart on täiesti tavaline vestlus sõnum. See ilmub otsingus, saab tsitaadiks ja jääb ajaloosse.
  • Selle saadab süsteemi saatja, mitte teie ettevõtte konto. See ilmub siiski selle kasutaja poolel, kes elementi käivitas, ja pealkirjas on märgitud, kelle süsteem kirjutab.
  • See, kes selle käitada võib, määratakse elemendi juures: ainult ettevõtte liikmed või ka välispool, kellega jagatakse vestlust. Kui teie ettevõte vestlusest lahkub, lõpeb õigus automaatselt.
  • API element aegunud tokeniga on puhkeolekus: praegused rakendused peidavad selle menüüs ja igasugune saadetud päring lükatakse serveris tagasi. A administraator salvestab selle jaoks uue tokeni, mis toimib ka vabastatud liidesel.

Seotud

Loomine ja vabastamine: Kohandatud elemendid: API liidesed. Täidetavad dokumendid liideste asemel: Kohandatud elemendid: Dokumendid.