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

Ideja në një fjali: Skava nuk e njeh fushën tuaj. Ajo njeh saktësisht një format, kartën. Ju vendosni se çfarë thotë ajo, ne kontrollojmë vetëm formën, madhësinë dhe sigurinë. Një urdhër materiali është një shembull; kompania tjetër mblidh reagimet e përdoruesve, ajo pas saj arkivon një foto vendi në regjistrat 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 tokenin e backend-it tuaj.
2. Dikush në bisedë plotëson formularin dhe e dërgon atë.
3. Skava thërret backend-in tuaj dhe dërgon vlerat e mbushura si JSON.
4. Përgjigja juaj bëhet karta në bisedë.
5. Opsionalisht, më vonë raportoni gjendje të reja përmes callback. Çdo raportim bëhet një kartë tjetër; ajo e mëparshme mbetet.

Kërkesat për backend-in tuaj

• HTTPS. Vetëm https://, jo http, pa kredenciale në adresë, maksimalisht 2000 karaktere.
• Arritshëm publikisht. Vargu i pritësit duhet të zgjidhet vetëm në IP publike. Localhost, rrjetet private, link-local dhe meta të dhënat e rethit të rethit refuzohen, dhe kjo kontrollohet në çdo thirrje.
• Adresë fikse. Skava zgjidh pritësin një herë dhe e fiks lidhjen në atë IP. Një ndryshim DNS gjatë thirrjes nuk ka efekt.
• Pa redirektim. Një 301 drejt adresës "saktë" llogaritet si dështim. Futni adresën përfundimtare menjëherë.
• Koha e përgjigjes. Kohëkufizimi është i konfigurueshëm për element dhe i kufizuar në 30 sekonda. Nëse keni nevojë për më shumë, përgjigjuni menjëherë dhe raportoni rezultatin më vonë përmes thirrjes së kthimit.
• Madhësia e përgjigjes. Skava lexon më së shumti 256 KiB.
• Lloji i përmbajtjes. Trupi analizohet vetëm me application/json.

Kërkesa që ju arrin

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

Autentifikimi është një krye emri dhe prefiksi i vlerës së të cilit konfigurohen në element, zakonisht Authorization me prefiks Bearer . Tokeni ruhet i enkriptuar tek ne. Kryet 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ë e ndërtoi elementin; vendosja nënstrukturë shfaqet vetëm aty ku ata shtuan një tabelë ose një përzgjedhë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": "…"}

Të tre kyçet 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 i përkthejmë tekstin tuaj.
• callback_url dhe callback_token: thirrja e kthyer për këtë ndërveprim të vetëm, shih më poshtë. Ato janë të pranishme vetëm kur thirrja vjen nga një bisedë.

Fushat e kontekstit si emri, kompania, projekti ose nënbiseda mbushen nga vetë serveri, të nxjerra nga kanali ku u ekzekutua elementi. Një klient i manipuluar nuk mund të pretendojë një emër tjetër projekti aty.

Përgjigja: formati i kartës

Përgjigju me 2xx dhe një objekt card. Kjo është saktësisht ajo që bëhet kartë 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 hartëzimi i përgjigjes i konfiguruar në element.
• title: titulli i kartës.
• state: vetëm ngjyra dhe toni i ikonës, njëra nga ok, pending, warn, error. Një vlerë e panjohur kthehet te ok dhe merrni një tregues.
• status_text: tekst i lirë që ne nuk e interpretojmë. Ajo ndodhet në krye të kartës dhe është gjithashtu ajo që shfaqet në listën e bisedave dhe në një njoftim push.
• fusha: një listë me label dhe value. Më së shumti 20 hyrje, label 80 karaktere, value 200, title dhe status_text 120 secila. Vlerat që janë shumë të gjata shkurtrohen, nuk refuzohen: një urdhërim nuk duhet të dështojë për shkak të një detaji.
• ikonë: shiko më poshtë.

Çfarë bën Skava me tekstin tuaj para se të arrijë në bisedë: heqet çdo kthesë rreshti dhe karakter kontroll (një karakter nga e djathta në të majtë mund të kthejë përndryshe shfaqjen e një shume), kthimet e prapme 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 imazhe 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.

hyrjet e përdoruesit i përkërket serverit: ato shfaqen në kartën e parë dhe nuk mund t'i mbishkruani. Në bisedë ato janë regjistri i asaj që u dërgua në fakt.

Ikona

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ë tuaj si një varg. Nga ai Skava merr vetëm gjeometrinë (path, circle, ellipse, rect, line, polyline, polygon me atributet e tyre numerike) dhe ndërton imazhin e vet. Skriptet, stilat, referencat e jashtme, foreignObject dhe atributet e ngjarjeve hedhen poshtë; një doctype ose një entitet çon në refuzim; skedari mund të jetë më së shumti 8 KiB dhe të përmbajë më së shumti 16 forma. Ngjyra, gjerësia e konturit dhe madhësia vendosen nga Skava, prandaj një ikonë nuk mund të fshehet si një kontroll. Punoni me një rrjet 24 me 24.

Pa icon mbetet shenja e parazgjedhur.

Thirrja e kthimit: raportimi i gjendjeve më vonë

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, trupin e kërkesës 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 një vlerë më të vogël ose të barabartë hedhet poshtë, kështu që dy raporte nuk mund t'i kalojnë njëri-tjetrit. Pa seq, fiton ai që mbërrin i fundit.
• final: mbyll ndërveprimin. Tokeni bëhet i pavlefshëm dhe nuk shfaqen më karta të tjera. Lejohet gjithashtu në përgjigjen e parë, për rrjedha pa ndjekje.
• notify: vendoseni në false për të publikuar kartën në heshtje, pa numër të pamë dhe pa njoftim. Për hapa ndërmjetës që nuk duhet të zgjojnë askënd. Pa të, karta është një mesazh krejtësisht normal.

Çdo raport bëhet karta e vet në bisedë, ai i mëparshmi mbetet. Kështu lexohet qartë cili gjendje u raportua. Nga kjo rrjedh një rekomandim: dërgoni vetëm atë që ka ndryshuar. Një kartë që përsërit numrin e porosive, 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ë publikojë më së shumti 50 karta. Një ndërveprim pranon raporte për 90 ditë.

Përgjigje të cilave duhet të reagoni

• 200 me {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Lexi sugjerimet: ato thonë se çfarë u shkurtua ose u hoq.
• 401: token ose ID ndërveprimi i gabuar. Mos e riprovoni.
• 410: ndërveprimi i mbyllur ose i skaduar. Mos e riprovoni.
• 422: kartë e papërdorshme, me sugjerime si arsye. Rregullojeni fillimisht.
• 400 JSON i dëmtuar, 413 shumë i madh, 429 shumë kërkesa (riprovoni me vonesë), 500 fajti ynë, riprovoni më vonë.

Shembulli 1: një urdhër me një histori 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ë pakete, 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: ndryshoi 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 të 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ë.

Shembulli 2: një veprim pa ndjekje

Jo çdo rrjedhë ka histori. Një element me një fushë të vetme që i kalon diçka sistemit tuaj 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 është e rëndësishme 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ë raportoni më asgjë.

Zgjedhësi i produkteve nga katalogu

Pas ngarkimit të katalogut të artikujve nga kompania, elementi mund të përmbajë bllokun zgjedhës produkti. Përdoruesi mblidh 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 kyçi është i lirë, kërko listën e parë që ka këtë formë, jo një emër të fiksuar. Para dërgimit, Skava kontrollon që çdo numër të ekzistojë vërtet në katalogun e atij kompanie, deri në 50 artikuj. Në kartë, artikujt shfaqen si listë me imazhin e produktit, emrin dhe sasinë.

Testimi

• Ping në redaktorin e elementit dërgon një HEAD të thjeshtë pa token dhe pa të dhëna. Përgjigju me çdo gjë; çdo përgjigje HTTP llogaritet si e arritshme.
• Kërkesë testimi kryen një thirrje reale me vlera shembull, edhe kur elementi është ende në draft, dhe tregon kërkesën, përgjigjen dhe mesazhet e validuesit të kartës.
• Parapamje në skedën pranë saj: ngjit JSON-in e përgjigjes tënde, kontrollo dhe do të shohësh kartën e përfunduar plus sugjerimet. Ajo kontrollohet në server me të njëjtën kod si në prodhim.
• Shërbues shembullor: një furnizues i plotë shembullor funksionon në api.skava.io dhe përdor gjithçka të përshkruar më lart. Burimi i tij ndodh në repozitorin nën example_order_server/, rreth 600 rreshta të bibliotekës standarde të pastër, të destinuar për t'u kopjuar.

Çfarë tjetër duhet të dini

• Karta është një mesazh bisede krejtësisht normal. 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 gjithsesi në anën e personit që e ka ekzekutuar elementin, dhe sistemi që shkruan përmendet në titull.
• Kush mund ta ekzekutojë atë vendoset në element: vetëm anëtarët e kompanisë, ose edhe të huajt që ndajnë një bisedë me të. Kur kompania juaj largohet nga biseda, leja mbaron vetvetiu.
• Një element API me një token të skaduar është i pafrymë dhe nuk shfaqet as në menunë derisa një administrator të ruajë një të ri.

Të lidhura

Krijimi dhe lëshimi: Elementë të Përshtatur: ndërfaqe API. Dokumentë të plotësueshëm në vend të ndërfaqeve: Elementë të Përshtatur: Dokumentë.