Šī lapa ir paredzēta izstrādātājiem, kuri savieno uzņēmuma backend sistēmu ar Skava. Kā tiek izveidots un publicēts API elements, ir aprakstīts lapā Pielāgotie elementi: API saskarnes; šeit mēs apskatām visu, kas notiek otras puses galā.

Ideja vienā teikumā: Skava nezina jūsu nozari. Tā precīzi zina tikai vienu formātu, proti, karti. Jūs nosakāt, kas tajā būs rakstīts, mēs pārbaudām tikai formu, izmēru un drošību. Materiālu pasūtījums ir viens piemērs; nākamais uzņēmums vāc lietotāju atsauksmes, bet vēl nākamais saglabā būvlaukuma fotogrāfiju savos reģistros.

Plūsmas kopsavilkums

1. Uzņēmuma administrators Skava izveido API elementu: veidlapu kopā ar jūsu backend adresi, metodi un tokeni.
2. Kāds sarunā aizpilda veidlapu un nosūta to.
3. Skava izsauc jūsu backend un nosūta aizpildītās vērtības kā JSON.
4. Jūsu atbilde kļūst par karti čatā.
5. Pēc izvēles vēlāk varat ziņot par jaunām stāvokļa izmaiņām caur atgriezenisko saiti. Katrs ziņojums kļūst par jaunu karti; iepriekšējā paliek.

Prasījumi jūsu backend

• HTTPS. Tikai https://, nevis http, bez pieteikšanās datiem adresē, ne vairāk kā 2000 rakstzīmes.
• Pieejams publiski. Hostam jāatbilst tikai publiskiem IP adresēm. Lokālais hosts, privātās tīklu adreses, link-local un mākoņa metadati tiek noraidīti, un tas tiek pārbaudīts katrā izsaukumā.
• Fiksēta adrese. Skava hostu izšķir vienu reizi un piesaista savienojumu pie šīs IP adreses. DNS maiņa izsaukuma laikā nav efektīva.
• Bez pāradresācijām. 301 pāradresācija uz „pareizo" adresi tiek uzskatīta par kļūdu. Ievadiet galīgo adresi uzreiz.
• Atbildes laiks. Laika limits ir konfigurējams katram elementam un stingri ierobežots līdz 30 sekundēm. Ja nepieciešams ilgāks laiks, atbildiet uzreiz un rezultātu ziņojiet vēlāk, izmantojot atgriezenisko saiti.
• Atbildes izmērs. Skava nolasīja ne vairāk kā 256 KiB.
• Satura tips. Ķermenis tiek analizēts tikai ar application/json.

Pie jums nonākošais pieprasījums

Metode ir GET, POST, PUT vai PATCH atkarībā no elementa. Ar POST, PUT un PATCH vērtības nonāk kā JSON ķermenis, ar GET kā vaicājuma parametri.

Autentifikācija ir viens virsraksts, kura nosaukums un vērtības prefikss ir konfigurēti elementā, parasti Authorization ar prefiksu Bearer . Tokenis mūsu pusē tiek glabāts šifrētā veidā. Virsrakstus host, content-length, content-type, cookie un accept-encoding nevar iestatīt.

Ķermenis ir plakans objekts. Atslēgas izvēlas elements izveidojošais; iekļaušanās parādās tikai tur, kur pievienota tabula vai produktu atlasītājs:

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

Trīs atslēgas vienmēr nāk no mums, tāpēc tās neizmantojiet pašiem:

• locale: lietotāja valodas kods. Atbildiet šajā valodā; mēs jūsu tekstus netulkojam.
• callback_url un callback_token: atgriezeniskā saite šai vienai mijiedarbībai, skatiet zemāk. Tās ir klāt tikai tad, ja izsaukums nāk no čata.

Konteksta lauki, piemēram, name, company, project vai subchat, tiek aizpildīti paša servera, izvedot tos no kanāla, kurā elements tika palaists. Pārkārtots klients tur nevar apgalvot citu projekta nosaukumu.

Atbilde: kartes formāts

Atbildiet ar 2xx un card objektu. Tieši tas kļūst par karti čatā:

{"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 (nepieciešams): vesels skaitlis 1. Kā teksts ("1") tas tiek noraidīts. Bez tā atbilde netiek uzskatīta par karti, un tiek piemērota elementā konfigurētā atbildes kartēšana.
• title: kartes virsraksts.
• state: tikai krāsa un ikonas tonis, viens no ok, pending, warn, error. Nezināma vērtība tiek aizstāta ar ok, un tiek parādīts paziņojums.
• status_text: brīvs teksts, ko mēs neinterpretējam. Tas atrodas kartes augšdaļā un tiek parādīts arī čata sarakstā un paziņojumā.
• fields: saraksts ar label un value. Ne vairāk kā 20 ieraksti, label 80 rakstzīmes, value 200, title un status_text pa 120. Pārāk garas vērtības tiek saīsinātas, nevis noraidītas: pasūtījumam nevajadzētu neizdoties detaļas dēļ.
• icon: skatiet zemāk.

Ko Skava dara ar jūsu tekstiem pirms tie nonāk čatā: tiek noņemti jaunu rindu simboli un vadības rakstzīmes (pareizs uz kreiso rakstzīme citādi varētu apgriezt summas attēlojumu), atzīmes tiek aizvietotas, un viss, kas sākas ar [SKAVA:, tiek neitralizēts. Pēdējais novērš situāciju, kad kartes vērtība tiktu interpretēta kā cits čata elements, piemēram, maksājuma pieprasījums.

Saites laukos, HTML un attēlos nevar iestatīt. Čats ir uzticams vide, un noklikšķināma adrese no ārējas backend sistēmas būtu aicinājums atjaunot pieteikšanās lapu.

Lietotāja ievades pieder serverim: tās parādās uz pirmās kartes, un jūs nevarat tās pārrakstīt. Čatā tās ir reģistrs par to, kas faktiski tika iesniegts.

Ikonas

Ar icon kartītei tiek piešķirta sava zīme virsrakstā. Divas iespējas:

Nosaukums no iekļautā komplekta: 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.

Vai jūsu pašu SVG kā virkne. No tā Skava izmanto tikai ģeometriju (path, circle, ellipse, rect, line, polyline, polygon ar to skaitliskajiem atribūtiem) un izveido savu attēlu. Skripti, stili, ārējās atsauces, foreignObject un notikumu atribūti tiek noraidīti; dokumanta tips vai entīte noved pie noraidīšanas; faila izmērs nedrīkst pārsniegt 8 KiB un tajā nedrīkst būt vairāk par 16 formām. Krāsu, kontūras biezumu un izmēru nosaka Skava, tāpēc ikona nevar izdoties par kontroles elementu. Strādājiet ar 24 reizināts 24 režģi.

Bez icon paliek noklusētā zīme.

Atpakaļsaucējs: vēlāku stāvokļu ziņošana

Aizsaukumā ir callback_url un callback_token. Izmantojiet tos, lai vēlāk ziņotu par jauniem stāvokļiem:

POST <callback_url> ar Authorization: Bearer <callback_token> un Content-Type: application/json, ķermenis ne vairāk kā 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}

Papildus kartītei ir trīs neobligātas vērtības:

• seq: jūsu pašu skaitītājs. Ziņojums ar mazāku vai vienādu vērtību tiek noraidīts, lai divi ziņojumi nevarētu viens otru apsteigt. Bez seq uzvar pēdējais ieradies ziņojums.
• final: noslēdz mijiedarbību. Tokenis kļūst nederīgs un turpmākas kartes vairs neparādās. Atļauts arī first atbildē plūsmām bez turpmākiem jautājumiem.
• notify: iestatiet uz false, lai karti publicētu klusē, bez nolasīto ziņojumu skaita un bez paziņojuma. Tas paredzēts starpposma soļiem, kas nevienam nedrīkst traucēt. Bez šīs iestatījuma karte ir pilnvērtīga parasta ziņojuma.

Katrs ziņojums kļūst par savu karti čatā, iepriekšējā paliek. Tādējādi ir skaidrs, kāds stāvoklis tika ziņots. No tā izriet ieteikums: nosūtiet tikai to, kas mainījās. Karte, kas ceturto reizi atkārto pasūtījuma numuru, pozīcijas un kopsummu, lasītājam ir tikai troksnis.

Divi ierobežojumi: tas pats ziņojums divas reizes nerada otro karti, un mijiedarbība var publicēt ne vairāk kā 50 kartes. Mijiedarbība pieņem ziņojumus 90 dienas.

Atbildes, uz kurām vajadzētu reaģēt

• 200 ar {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Izlasi norādes: tās norāda, kas ir saīsināts vai izlaists.
• 401: nepareizs tokens vai mijiedarbības ID. Nemēģiniet atkārtoti.
• 410: mijiedarbība ir noslēgta vai termiņš ir beidzies. Nemēģiniet atkārtoti.
• 422: karte nav lietojama, ar hints kā iemeslu. Vispirms to labojiet.
• 400 bojāts JSON, 413 pārāk liels, 429 pārāk daudz pieprasījumu (atkārtojiet ar aizkavēšanos), 500 mūsu kļūda, atkārtojiet vēlāk.

Piemērs 1: pasūtījums ar statusa vēsturi

1. solis, pieprasījums jūsu serverim:

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

2. solis, jūsu tūlītējā atbilde:

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

Čatā tagad tiek parādīta karte ar sūtījuma ikonu, statusu un lietotāja ievadi.

3. solis, vēlāk, veicot izvēli:

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

Mierīga otrā karte bez laukiem: mainījies tikai statuss.

4. solis, nosūtīšanas brīdī:

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}

Šī karte varētu kādu pamodināt, tāpēc nav notify: false.

5. solis, piegādes brīdī:

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

Ar final mijiedarbība ir noslēgta un tokens vairs nedarbojas.

Piemērs 2: darbība bez turpmākiem soļiem

Ne katram plūsmas procesam ir vēsture. Elementam ar vienu lauku, kas nodod kaut ko jūsu sistēmai, ir nepieciešama tikai viena atbilde:

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

Šeit ir svarīgs final: true: citādi mijiedarbība paliktu atvērta 90 dienas ar derīgu tokeni, pat ja jūs vairs nekad neziņosiet neko.

Produkta izvēlētājs no kataloga

Kad uzņēmums ir augšupielādējis savu produktu katalogu, elements var saturēt produkta izvēlētāja bloku. Lietotājs no tā sastāda grozu, un jūs to saņemat kā saraksti ar atslēgu, ko izvēlējies elements izveidojošais:

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

Tā kā atslēga ir brīva, meklējiet pirmo sarakstu ar šādu formu, nevis fiksētu nosaukumu. Pirms nosūtīšanas Skava pārbauda, vai katrs numurs tiešām eksistē šīs uzņēmuma katalogā, ne vairāk kā 50 pozīcijas. Kartītē pozīcijas parādās kā saraksts ar produkta attēlu, nosaukumu un daudzumu.

Testēšana

• Ping elementa redaktorā nosūta tukšu HEAD bez tokena un bez datiem. Atbildiet ar jebko; jebkura HTTP atbilde tiek uzskatīta par sasniedzamu.
• Testa pieprasījums veic reālu izsaukumu ar parauga vērtībām, pat ja elements vēl ir melnraksts, un parāda pieprasījumu, atbildi un kartītes validatora ziņojumus.
• Priekšskatījums blakus esošajā cilnē: ielīmējiet atbildes JSON, pārbaudiet, un redzēsiet gatavo kartīti kopā ar norādēm. Tas tiek pārbaudīts serverī ar tādu pašu kodu kā ražošanas vidē.
• Piemēra serveris: pilnībā funkcionējošs piegādātājs darbojas api.skava.io un izmanto visu iepriekš aprakstīto. Tā avota kods atrodas repozitorijā mapei example_order_server/, aptuveni 600 rindas tīras standarta bibliotēkas, paredzētas kopēšanai.

Citas lietas, kas jums jāzina

• Karte ir pilnīgi parasta čata ziņojuma. Tā parādās meklējumā, to var citēt un tā paliek vēsturē.
• To nosūta sistēmas sūtītājs, nevis jūsu uzņēmuma konts. Tā joprojām parādās tās personas pusē, kas izpildīja elementu, un nosaukumā norādīts, kura sistēma to raksta.
• Kam ir atļauts to izpildīt, ir noteikts elementā: tikai uzņēmuma biedri vai arī ārpusē esošie, kas koplieto čatu ar to. Kad jūsu uzņēmums atstāj čatu, atļauja automātiski beidzas.
• API elements with an expired token are dormant and do not appear in the menu until an admin stores a new one.

Saistīts

Izveide un publicēšana: Pielāgotie elementi: API saskarnes. Aizpildāmi dokumenti nevis saskarnes: Pielāgotie elementi: Dokumenti.