Skava Skava / Wiki

Lidhja e Elementeve të Personalizuara për zhvilluesit

Kjo faqe është për zhvilluesit që lidhin backend-in e një kompanie me Skava. Si krijohet dhe publikohet një element API trajtohet në Elementet e Personalizuara: ndërfaqet API; këtu mbulojmë gjithçka që duhet të ndodhë në skajin tjetër të vijës.

Ideja në një fjali: Skava nuk e njeh fushën tuaj. Ajo njeh saktësisht një format, kartën. Ti vendos se çfarë thotë, ne kontrollojmë vetëm formën, madhësinë dhe sigurinë. Një porosi materiali është një shembull; kompania tjetër merr feedback nga përdoruesit, ajo pas saj arkivon një foto vendi në regjistrimet e saj.

Rrjedha në një vështrim

  1. Një administrator kompanie krijon një element API në Skava: një formular plus adresën, metodën dhe token-in e backend-it tuaj.
  2. Dikush në bisedë plotëson formularin dhe e dërgon.
  3. Skava thërret backend-in tuaj dhe dërgon vlerat e plotësuara si JSON.
  4. Përgjigja juaj bëhet karta në bisedë.
  5. Opsionalisht, më vonë raportoni gjendje të reja përmes callback. Çdo raport bëhet një kartë tjetër; ajo e mëparshme mbetet.

Kërkesat për backend-in tuaj

  • HTTPS. Vetëm https://, pa http, pa kredenciale në adresë, maksimumi 2000 karaktere.
  • I arritshëm publikisht. Hosti duhet të zgjidhet vetëm në IP publike. Localhost, rrjete private, link-local dhe metadata e cloud-it refuzohen, dhe kjo kontrollohet në çdo thirrje.
  • Adresë e fikse. Skava zgjidh hostin një herë dhe fiks lidhjen në atë IP. Një ndryshim DNS gjatë thirrjes nuk ka efekt.
  • Pa redirektues. Një 301 drejt adresës "të saktë" llogaritet si dështim. Shënoni adresën përfundimtare menjëherë.
  • Koha e përgjigjes. Koha e kufirit është e konfigurueshme për element dhe e kufizuar rreptësisht në 30 sekonda. Nëse keni nevojë për më shumë, përgjigjuni menjëherë dhe raportoni rezultatin më vonë përmes callback.
  • Madhësia e përgjigjes. Skava lexon deri në 256 KiB.
  • Content-Type. Trupi analizohet vetëm me application/json.

Kërkesa që arrin te ti

Metoda është GET, POST, PUT ose PATCH, në varësi të elementit. Me POST, PUT dhe PATCH vlerat mbërrijnë si trup JSON, me GET si parametra pyetjeje.

Autentifikimi është një kopshtë emri dhe prefiksi i vlerës të cilat konfigurohen në element, zakonisht Authorization me prefiksin Bearer . Tokeni ruhet i enkriptuar te ne. Kopshtët host, content-length, content-type, cookie dhe accept-encoding nuk mund të vendosen.

Trupi është një objekt i sheshtë. Çelësit zgjidhen nga ai që ndërtoi elementin; anilimi shfaqet vetëm aty ku ata shtuan një tabelë ose një zgjedhës produkti:

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

Tre çelës vijnë gjithmonë nga ne, prandaj mos i përdorni vetë:

  • locale: kodi i gjuhës së përdoruesit. Përgjigjuni në atë gjuhë; ne nuk përkthejmë tekstet tuaja.
  • callback_url dhe callback_token: thirrja kthimore për këtë ndërveprim të vetëm, shihni më poshtë. Ato janë të pranishme vetëm kur thirrja vjen nga një bisedë.

Fushat e kontekstit si emri, kompania, projekti ose nënbiseda plotësohen nga vetë shërbyesi, të nxjerra nga kanali ku u ekzektua elementi. Një klient i manipulluar nuk mund të pretendojë një emër tjetër projekti aty.

Përgjigja: formati i kartës

Përgjighu me 2xx dhe një objekt card. Kjo është saktësisht ajo që bëhet karta në bisedë:

{"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 (e detyrueshme): numri i plotë 1. Si tekst ("1") refuzohet. Pa të, përgjigja nuk llogaritet si kartë dhe zbatohet hartimi i përgjigjeve i konfiguruar në element.
  • title: titulli i kartës.
  • state: vetëm ngjyra dhe toni i ikonës, njëri nga ok, pending, warn, error. Një vlerë e panjohur kthehet te ok dhe merr një tregues.
  • status_text: tekst i lirë që nuk e interpretojmë. Ai ndodhet në krye të kartës dhe është gjithashtu ajo që shfaqet në listën e bisedave dhe në një njoftim push.
  • fields: një listë e label dhe value. Deri në 20 hyrje, label 80 karaktere, value 200, title dhe status_text 120 sec. Vlerat që janë shumë të gjata shkurtësohen, nuk refuzohen: një porosi nuk duhet të dështojë për shkak të një detaji.
  • icon: shih më poshtë.

Çfarë bën Skava me tekstet tuaja para se të arrijnë në bisedë: hapet e reja dhe karakteret e kontrollit hiqen (një karakter nga djathtas në majtas mund të kthejë përndryshe shfaqjen e një shifre), backticks zëvendësohen, dhe çdo gjë që fillon me [SKAVA: neutralizohet. E fundit parandalon që një vlerë karte të lexohet si një element tjetër bisede, për shembull një kërkesë pagese.

Lidhjet në fusha, HTML dhe imazhet nuk mund të vendosen. Një bisedë është një mjedis i besuar, dhe një adresë e klikueshme nga një backend i huaj do të ishte një ftesë për të rindërtuar një faqe hyrjeje.

Hyrimat e përdoruesit i përkasin serverit: ato shfaqen në kartën e parë dhe nuk mund t'i mbivendosësh. Në bisedë ato janë regjistri i asaj që u dërgua realisht.

Ikonat

Me icon karta merr shenjën e vetë në krye. Dy mënyra:

Një emër nga grupi i përfshirë: 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.

Ose SVG-në tënde si varg. Nga kjo Skava merr vetëm gjeometrinë (path, circle, ellipse, rect, line, polyline, polygon me atributet e tyre numerike) dhe ndërton imazhin e vet. Skriptet, stilet, referencat e jashtme, foreignObject dhe atributet e ngjarjeve hiqen; një doctype ose një entitet çon në refuzim; skedaja mund të jetë deri në 8 KiB dhe të përmbajë deri në 16 forma. Ngjyra, gjerësia e vijave dhe madhësia vendosen nga Skava, kështu që një ikonë nuk mund të maskohet si kontroll. Puno me një rrjetë 24 me 24.

Pa icon, mbetet shenja e parazgjedhur.

Callback: raportimi i gjendjeve të mëvonshme

Thirrja përmban callback_url dhe callback_token. Përdorini ato për të raportuar gjendje të reja më vonë:

POST <callback_url> me Authorization: Bearer <callback_token> dhe Content-Type: application/json, trup deri në 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}

Përveç kartës, ka tre vlera opsionale:

  • seq: numëruesi juaj. Një raport me vlerë më të vogël ose të barabartë hiqet, kështu që dy raporte nuk mund të kalojnë njëra-tjetrën. Pa seq, fiton ai që mbërrin i fundit.
  • final: mbyll ndërveprimin. Tokeni bëhet i pavlefshëm dhe nuk shfaqen më karta. Lejohet edhe në përgjigjen të parë, për rrjedha pa ndjekje.
  • notify: vendoseni si false për të postuar kartën në heshtje, pa numër të pa lexuara dhe pa njoftim. Për hapa ndërmjetës që nuk duan të zgjojnë askënd. Pa këtë, karta është një mesazh i rregullt.

Çdo raport bëhet kartë e vetë në bisedë, ndërsa e mëparshmba mbetet. Kështu lexohet lehtësisht cila gjendje u raportua. Nga kjo rrjedh një rekomandim: dërgoni vetëm atë që ndryshoi. Një kartë që përsërit numrin e porosisë, artikujt dhe totalin për herë të katërt është thjesht zhurmë për lexuesin.

Dy kufizime: i njëjti raport dy herë nuk prodhon një kartë të dytë, dhe një ndërveprim mund të postojë deri në 50 karta. Një ndërveprim pranon raporte për 90 ditë.

Përgjigjet që duhet të reagojë

  • 200 me {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Lexo udhëzimet: ato tregojnë çfarë u shkurtua ose u hoq.
  • 401: token i gabuar ose id ndërveprimi. Mos ripërsërit.
  • 410: ndërveprimi u mbyll ose skaduan. Mos ripërsërit.
  • 422: karta e papërdorshme, me hints si arsye. Riparoje fillimisht.
  • 400 JSON i keq, 413 shumë i madh, 429 shumë kërkesa (ripërsërit me pranimë), 500 gabimi ynë, ripërsërit më vonë.

Shembull 1: një porosi me historik statusi

Hapi 1, kërkesa te backend-i juaj:

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

Hapi 2, përgjigja juaj e menjëhershme:

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

Biseda tani shfaq një kartë me një ikonë paketi, statusin dhe hyrjet e përdoruesit.

Hapi 3, më vonë gjatë zgjedhjes:

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

Një kartë e dytë e qetë pa fusha: u ndryshua vetëm statusi.

Hapi 4, në dërgesë:

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}

Kjo kartë mund ta zgjojë dikë, prandaj nuk ka notify: false.

Hapi 5, në dorëzim:

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

Me final ndërveprimi mbyllet dhe tokeni nuk funksionon më.

Shembull 2: një veprim pa ndjekje

Nuk çdo rrjedhë ka histori. Një element me një fushë të vetme që i kalon diçka sistemit tënd kërkon vetëm një përgjigje:

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

final: true ka rëndësi këtu: përndryshe ndërveprimi do të mbetej i hapur për 90 ditë me një token të vlefshëm, edhe pse nuk do të raportosh më asgjë.

Zgjedhës produkti nga katalogu

Nëse kompania ka ngarkuar katalogun e saj artikujsh, elementi mund të përmbajë bllokun zgjedhës produkti. Përdoruesi mban një shportë prej tij, dhe ju e merrni si listë nën çelësin e zgjedhur nga ai që e ndërtoi elementin:

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

Meqenëse çelësi është i lirë, kërko listën e parë që ka këtë formë, jo një emër të fiksuar. Para se të dërgohet, Skava kontrollon që çdo numër ekziston realisht në katalogun e atij kompanie, me maksimum 50 artikuj. Në kartë, artikujt shfaqen si listë me imazh produkti, emër dhe sasi.

Testimi

  • Ping në editorin e elementit dërgon një HEAD të thjeshtë pa token dhe pa të dhëna. Përgjigjuni me çfarëdo; çdo përgjigje HTTP llogaritet si e arritshme.
  • Kërkesë testi njofton një thirrje reale me vlera shembull, edhe kur elementi është ende në skicë, dhe tregon kërkesën, përgjigjen dhe mesazhet e validuesit të kartës.
  • Parapamje në skedën pranë saj: ngjishni përgjigjen tuaj JSON, kontrolloni dhe do të shihni kartën e përfunduar si dhe udhëzimet. Ajo kontrollohet në server me të njëjtin kod si në prodhim.
  • Server shembull: një furnizues i plotë shembullish ekziston në api.skava.io dhe përdor gjithçka të përshkruar më lart. Burimi i tij ndodhet në repozitorin nën example_order_server/, rreth 600 rreshta e pastër bibliotekë standarde, i menduar për t'u kopjuar.

Çfarë tjetër duhet të dini

  • Karta është një mesazh bisede i rregullt. Ajo shfaqet në kërkim, mund të citohet dhe mbetet në historik.
  • Ajo dërgohet nga dërguesi i sistemit, jo nga një llogari e kompanisë suaj. Ajo shfaqet ende në anën e personit që ekzekutoi elementin, dhe se cili sistem po shkruan thuhet në titull.
  • Kush mund ta ekzekutojë përcaktohet në element: vetëm anëtarët e kompanisë, ose edhe jashtë anëtarëve që ndajnë një bisedë me të. Kur kompania juaj largohet nga biseda, leja mbaron automatikisht.
  • Një element API me një token të skaduar është inaktiv: aplikacionet aktuale e fshehin atë në menu, dhe një thirrje e dërguar prapëseprapë refuzohet në server. Një administrator ruaj një token të ri për të, gjë që funksionon edhe në një ndërfaqe të lëshuar.

Të lidhura

Krijimi dhe lëshimi: Elemente të personalizuara: Ndërfaqe API. Dokumentë plotësues në vend të ndërfaqeve: Elemente të personalizuara: Dokumente.