Skava Skava / Wiki

Pielāgoto elementu savienošana izstrādātājiem

Šī lapa ir paredzēta izstrādātājiem, kas savieno uzņēmuma aizmugures daļu ar Skavu. API elementa izveides un publicēšanas process ir aprakstīts sadaļā Pielāgotie elementi: API saskarnes; šeit mēs aplūkojam visu, kas jāveic otras puses galā.

Ideja vienā teikumā: Skava nezina jūsu nozari. Tā zina tikai vienu formātu, proti, karti. Jūs nosakāt tās saturu, 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 arhivē būvlaukuma fotogrāfijas savos ierakstos.

Plūsmas pārskats

  1. Uzņēmuma administrators izveido API elementu Skavā: formu, kā arī jūsu aizmugures daļas adresi, metodi un tokeni.
  2. Kāds tērzēšanā aizpilda formu un to nosūta.
  3. Skava izsauc jūsu backendu un nosūta aizpildītās vērtības kā JSON.
  4. Jūsu atbilde kļūst par karti tērzēšanā.
  5. Pēc vēlēšanās vēlāk ziņojat par jaunām stāvokļa izmaiņām caur atgriezenisko saiti. Katrs ziņojums kļūst par citu karti, bet iepriekšējā paliek.

Prasījumi jūsu backendam

  • HTTPS. Tik https://, bez http, bez pieteikšanās datiem adresē, ne vairāk kā 2000 rakstzīmes.
  • Pieejams publiski. Hostam jāatrisinās tikai uz publiskām IP adresēm. Lokālā vietne, privātās tīkli, saistītie tīkli un mākoņa metadati tiek noraidīti, un tas tiek pārbaudīts katrā izsaukumā.
  • Fiksēta adrese. Skava atrisina hostu vienu reizi un fiksē savienojumu uz šo IP. DNS izmaiņas izsaukuma laikā nav ietekmes.
  • Bez pārvirzījumiem. 301 pārvirzījums uz "pareizo" adresi tiek uzskatīts par kļūdu. Ievadiet gala adresi uzreiz.
  • Atbildes laiks. Laika limits ir konfigurējams katram elementam un stingri ierobežots ar 30 sekundēm. Ja nepieciešams ilgāks laiks, atbildiet uzreiz un ziņojiet par rezultātu vēlāk caur atgriezenisko saiti.
  • Atbildes izmērs. Skava lasa ne vairāk kā 256 KiB.
  • Content-Type. Teksts tiek apstrādāts tikai ar application/json.

Pieprasījums, kas nonāk pie jums

Metode ir GET, POST, PUT vai PATCH, atkarībā no elementa. Ar POST, PUT un PATCH vērtības tiek nosūtītas kā JSON teksts, ar GET kā vaicājuma parametri.

Autentifikācija ir viena galviņa, kuras nosaukums un vērtības prefikss ir iestatīti elementā, parasti Authorization ar prefiksu Bearer . Tokenis tiek uzglabāts šifrētā formā mūsu pusē. Galviņas host, content-length, content-type, cookie un accept-encoding nevar iestatīt.

Korpus ir plakans objekts. Atslēgas izvēlas tas, kas izstrādāja elementu; iekļaušana parādās tikai tur, kur pievienots tabula vai produktu izvēlē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 neizmantojiet tās pats:

  • locale: lietotāja valodas kods. Atbildiet šajā valodā; mēs nevērsiet jūsu tekstus.
  • callback_url un callback_token: atgriezeniskais saukums šai vienai mijiedarbībai, skatiet zemāk. Tie ir klāt tikai tad, ja izsaukums nāk no tērzēšanas.

Konteksta lauki, piemēram, vārds, uzņēmums, projekts vai apakšsaruna, tiek aizpildīti paši no servera, izvedot no kanāla, kurā elements tika palaists. Pārbaudīts klients nevar tur apgalvot citu projekta nosaukumu.

Atbilde: kartes formāts

Atbildiet ar 2xx un card objektu. Tieši tas kļūst par karti tērzē:

{"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 (obligāts): vesels skaitlis 1. Kā teksts ("1") tas tiek noraidīts. Bez tā atbilde netiek uzskatīta par karti, un tiek piemērota elementā iestatītā atbilžu kartēšana.
  • title: kartes virsraksts.
  • state: tikai krāsa un ikonas toņs, viens no ok, pending, warn, error. Nezināma vērtība atgriežas pie ok, un jūs saņemat norādi.
  • status_text: brīva teksta daļa, ko mēs neinterpretējam. Tā atrodas kartes augšdaļā un tiek rādīta arī tērzēšanas sarakstā un push paziņojumos.
  • fields: saraksts ar label un value. Maksimāli 20 ieraksti, label 80 rakstzīmes, value 200, title un status_text katrs 120. Pārāk garas vērtības tiek samazinātas, nevis noraidītas: pasūtījumam nevajadzētu kļūt par kļūdu detaļu dēļ.
  • icon: skatīt zemāk.

Ko Skava dara ar jūsu tekstiem, pirms tie nonāk tērzēšanā: rindu pārneses un vadības rakstzīmes tiek noņemtas (labi uz kreiso rakstzīme citādi var apgriezt summas attēlojumu), apgrieztie komati tiek aizstāti, un viss, kas sākas ar [SKAVA:, tiek neitralizēts. Pēdējais pasākums novērš kartes vērtības nolasīšanu kā citu tērzēšanas elementu, piemēram, maksājuma pieprasījumu.

Saites laukos, HTML un attēlos nevar iestatīt. Tērzēšana ir uzticams vide, un klikšķināma adrese no ārpuses backend sistēmas būtu aicinājums pārbūvēt pieteikšanās lapu.

Lietotāja ievades pieder serverim: tās parādās pirmajā kartē un tās nevar pārrakstīt. Tērzējumā tās ir ieraksts par to, kas faktiski tika iesniegts.

Ikoniņas

Ar icon karte iegūst savu atzīmi galvenajā daļā. Divi veidi:

Vārds no iekļautā kopuma: 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ša SVG kā virkne. No tā Skava ņem tikai ģeometriju (path, circle, ellipse, rect, line, polyline, polygon ar to skaitliskajām atribūtām) un izveido savu attēlu. Skripti, stili, ārējās atsauces, foreignObject un notikumu atribūtas tiek noraidītas; dokumenta tips vai entīte noved pie noraidīšanas; failam drīkst būt ne vairāk kā 8 KiB un saturēt ne vairāk kā 16 formas. Krāsu, līnijas biezumu un izmēru nosaka Skava, tāpēc ikoniņa nevar izskatīties kā vadīšanas elements. Strādājiet ar 24 x 24 režģi.

Bez icon paliekoties noklusējuma zīme.

Atsaukums: vēlāku stāvokļu ziņošana

Aizvanījumā ir iekļauti 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 kartei 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 apdzīt viens otru. Bez seq spēkā paliek pēdējais ienākošais.
  • final: noslēdz mijiedarbību. Žetons kļūst nederīgs un vairs neuzrāda kartītes. Atļauts arī pirms atbildē plūsmām bez turpmākām darbībām.
  • notify: iestatiet uz false, lai kartīte tiktu publicēta klusumā, bez nolasīto skaitītāja un bez paziņojuma. Piemērots starpposmiem, kas nevajag modināt nevienu. Bez šī iestatījuma kartīte ir parasta ziņa.

Katrs ziņojums kļūst par savu kartīti tērzē, iepriekšējā paliek. Tādējādi ir skaidri redzams, kāds stāvoklis tika ziņots. No tā izriet ieteikums: sūti tikai to, kas mainījās. Kartīte, kas ceturto reizi atkārto pasūtījuma numuru, pozīcijas un kopsummu, ir tikai troksnis lasītājam.

Divi ierobežojumi: divreiz tas pats ziņojums nerada otro kartīti, un viena mijiedarbība var publicēt ne vairāk kā 50 kartītes. Mijiedarbība pieņem ziņojumus 90 dienas.

Atbildes, uz kurām jāreaģē

  • 200 ar {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Izlasi norādes: tās norāda, kas tika saīsināts vai izlaists.
  • 401: nepareiza letora vai mijiedarbības id. Nemēģini vēlreiz.
  • 410: mijiedarbība aizvēra vai beidza derīguma termiņu. Nemēģini vēlreiz.
  • 422: karte nederīga, ar hints kā iemeslu. Vispirms to labi.
  • 400 bojāts JSON, 413 pārāk liels, 429 pārāk daudz pieprasījumu (atkārtojiet ar aizkavi), 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 aizmugures daļai:

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 nekavējoties sniegtā 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"}]}}

Tērzējumā tagad tiek rādīta karte ar pakas ikonu, statusu un lietotāja ievadītajiem datiem.

3. solenis, vēlāk izvēloties:

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

Klusā otrā karte bez laukiem: mainījās tikai statuss.

4. solenis, nosūtot:

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 pamodināt kādu, tāpēc nav notify: false.

5. solenis, piegādājot:

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 tiek aizslēgta un tokens vairs nedarbojas.

Piemērs 2: darbība bez turpmākām darbībām

Ne katram plūsmam 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, lai gan jūs vairs nekad neiesniegtu neko.

Produktu izvēlētājs no kataloga

Kad uzņēmums ir augšupielādējis savu rakstu katalogu, elements var saturēt produktu atlasītāja bloku. Lietotājs no tā veido grozu, un jūs to saņemat kā sarakstu zem atslēgas, ko izvēlējās elements izstrādājis:

{"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 patiešām eksistē šī uzņēmuma katalogā, ne vairāk kā 50 pozīcijas. Kartē pozīcijas tiek rādītas kā saraksts ar produkta attēlu, nosaukumu un daudzumu.

Testēšana

  • Ping elementu redaktorā nosūta tukšu HEAD pieprasījumu bez tokena un bez datiem. Atbildiet ar jebko; jebkura HTTP atbilde tiek uzskatīta par sasniedzamu.
  • Testa pieprasījums izpilda reālu izsaukumu ar parauga vērtībām, pat ja elements vēl ir melnrakstā, un parāda pieprasījumu, atbildi un kartes validatora ziņas.
  • Priekšskatījums blakus esošajā cilpā: ielīmējiet savu atbildes JSON, pārbaudiet, un redzēsiet pabeigtu karti un norādes. Tas tiek pārbaudīts serverī ar tādu pašu kodu kā produkcijā.
  • Piemēra serveris: pilnīgs piemēra piegādātājs darbojas api.skava.io un izmanto visu iepriekš minēto. Tā avots atrodas repozitorijā example_order_server/ katalogā, aptuveni 600 rindu tīra standarta bibliotēka, paredzēts kopēšanai.

Ko vēl vajadzētu zināt

  • Karte ir parasta čata ziņa. Tā parādās meklēšanā, to var citēt un tā paliek vēsturē.
  • To nosūta sistēmas sūtītājs, nevis jūsu uzņēmuma konts. Tomēr tā parādās tā puses, kas izpildīja elementu, pusē, un nosaukumā norādīts, kura sistēma to raksta.
  • Tas, kas to var izpildīt, ir iestatīts elementā: tikai uzņēmuma locekļi vai arī ārpersonas, kas koplieto čatu ar to. Kad jūsu uzņēmums pamet čatu, atļauja beidzas automātiski.
  • API elements ar beigušos derīguma termiņa tokeni ir neaktīvs: pašreizējās lietotnes to slēp izvēlnē, un izsaukums, kas tomēr tiek nosūtīts, tiek noraidīts serverī. Administrators saglabā jaunu tokeni, kas darbojas arī izlaistajā saskarnē.

Saistītie

Izveide un izlaišana: Pielāgotie elementi: API saskarnes. Pildāmi dokumenti vietā saskarnēm: Pielāgotie elementi: Dokumenti.