Elementet e Përshtatura: API

Një ndërfaqe API është një formular ku vlerat e mbushura Skava i dërgon si JSON në një adresë që ju specifikoni (backend-i juaj). Kështu mund të lidhni Skava-n në mënyrë të sigurt me sistemet tuaja.

Konfiguroni një ndërfaqe API

Një ndërfaqe përbëhet nga fushat e hyrjes (ato formojnë JSON), adresa synim dhe autentifikimi.

1. Krijoni fusha: Çdo fushë merr një çelës JSON. Në të djathtë shihni në kohë reale parashikimin JSON, i cili dërgohet te backend-i juaj saktësisht kështu.
2. Drejtimi (URL): adresa https:// e backend-it tuaj. Lejohen vetëm drejtimet HTTPS dhe publikisht të aksesueshme (shiko Sigurimin më poshtë).
3. Metoda: POST (parazgjedhje), PUT, PATCH ose GET. Me GET vlerat shtohen si parametra pyetjeje në vend që të dërgohen në trupin e kërkesës.
4. Autentifikimi: Vendosni emrin e kryes (p.sh. Authorization) dhe prefiksin e vlerës (p.sh. Bearer ), më pas ruajeni tokenin. Opsionalisht vendosni një datë skadence.
5. Fushat e përgjigjes (opsionale): Përcaktoni rrugën se cilat vlera nga përgjigja e backend-it duhet të shfaqen: p.sh. order.id ose items[0].sku.
6. Kontrolloni me Ping dhe Kërkesë Testi, më pas Lëshoni.

Ruajeni token-in në mënyrë të sigurtë

Token-i ruhet i enkriptuar dhe kurrë nuk kthehet te klientët: aplikacioni tregon vetëm se nëse është vendosur një token dhe kur skadon. Kur dërgon, Skava e shton atë në anën e serverit te kryetari i konfiguruar. Nëse vendosni një datë skadence, Skava e refuzon thirrjen pas skadencës dhe ju kërkon të rinovoni token-in.

Testimi: Ping dhe Kërkesë Testi

• Ping : një kontroll i lehtë i arritshmërisë. Ai kontrollon vetëm se adresa juaj përgjigjet dhe nuk dërgon token apo të dhëna formulari gjatë procesit. Tregon arritshmërinë, statusin dhe kohën e përgjigjes. Ideal si hap i parë.
• Kërkesë Testi : provimi i vërtetë: dërgon të dhëna shembull duke përfshirë token te adresa juaj dhe ju tregon përgjigjen e plotë si dhe fushat e përgjigjes të nxjerra.

Si administrator, mund të ekzekutoni të dyja ndërsa jeni ende në mënyrën e draftit për të verifikuar integrimin para lëshimit.

Përgatitje dhe Lëshim

Çdo ndërfaqe fillon si shpesh dhe mund të përditësohet lirshëm. Kur gjithçka është e gatshme, e lëshoni me Lëshim.

Siguria

Si përdor ekipi një ndërfaqe të lëshuar

Nëse një ndërfaqe është lëshuar, të gjithë anëtarët e kompanisë mund ta aktivizojnë atë drejtpërdrejt nga një bisedë: nuk kërkohet redaktor. Rrjedha është e njëjtë si me shabllonet e dokumenteve: zgjidh, plotëso, dërgo.

1. Në bisedë, shtyp Plus në fund dhe zgjidh Element të Përshtatur.
2. Zgjidh shabllonin ose ndërfaqen e dëshiruar nga lista.
3. Plotëso formularin dhe Dërgo.
4. Rezultati shfaqet si kartë në bisedë: i dukshëm për të gjithë në bisedë.

Lejoni që AI të ndërtojë një element

Si administrator i kompanisë, nuk duhet të përdorni vetë redaktorin. Thoni asistentit të Skava në bisedë, për shembull "ndërtoje një formular porosite për katalogun tim me sasi dhe adresë dërgese". Ai krijon një skicë nga kjo, mund të ndryshojë fushat një nga një më vonë dhe di katalogun e artikujve që keni ngarkuar: për porositë sugjeron zgjedhësin e produkteve në vend të një fushe teksti për numrin e artikullit.

Çfarë mund të vendosë gjithashtu: pikën e fundit dhe metodën si dhe audienca ("vetëm anëtarët e kompanisë" ose "gjithashtu të huajt në të njëjtën bisedë"). Për audienca pyet fillimisht në vend që ta vendosë menjëherë, sepse vendos kush mund të ekzekutojë diçka nga jashtë.

Çfarë nuk prek qartësisht: tokenin e qasjes. Asnjëherë nuk kërkon njërin dhe asnjëherë nuk pranon njërin, sepse mesazhet e bisedës ruhen. Ju e hyni vetë atë në redaktor, përndryshe nuk dërgohet asnjë thirrje. Dhe nuk mund të publikojë: hapi i fundit mbetet në duart tuaja, kështu që asgjë nuk bëhet e dukshme për klientët pa u kontrolluar.

Kush mund ta ekzekutojë atë

Fletorja "Pika e fundit" thotë kush mund të përdorë një element. Vlera e parazgjedhur janë anëtarët e kompanisë suaj. Vendosja e dytë e hap atë për të huajt, por vetëm në një bisedë ku është i pranishëm dikush nga kompania juaj gjithashtu: saktësisht rasti për të cilin është menduar, klienti që porosit nga ju. Kur kompania juaj largohet nga biseda, leja mbaron vetvetiu.

Produktet nga katalogu juaj

Pas ngarkimit të katalogut tuaj të artikujve, ndërtuesi ofron një bllok zgjedhës produkti. Nuk ka opsione për mirëmbajtje: lista është katalogu juaj. Personi që bën porosinë e kërkon, sheh imazhin, emrin dhe numrin e artikullit, dhe backend-i juaj merr numrin e artikullit. Skava refuzon një numër që nuk është në katalogun tuaj. Për sasinë, vendosni një fushë normale numri pranë tij.

Përcaktoni kartën vetë

Backend-i juaj vendos se çfarë thotë karta. Skava kontrollon vetëm formën, madhësinë dhe sigurinë, kurrë kuptimin: ajo nuk di gjendjet e porosive as emrat e fushave. Për ta bërë këtë, përgjigjuni me një objekt card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v duhet të jetë numri i plotë 1. Pa të, përgjigja nuk llogaritet si kartë dhe zbatohet hartëzimi i përgjigjes i konfiguruar në element.
• state është vetëm ngjyra dhe ikona: ok, pending, warn ose error. Çdo gjë që bart kuptim vendoset në status_text si tekst i lirë.
• fields është një listë me etiketa dhe vlera, me maksimum 20 hyrje. Vlerat që janë shumë të gjata shkurtrohen në vend që të refuzohen, kështu që një urdhër kurrë nuk dështon për shkak të një detaji.

Hyrjet e përdoruesit i përkasin serverit: ato mbeten të paprekura pavarësisht se çfarë dërgon backend-i juaj. Ato janë regjistrimi në bisedë se çfarë u dërgua në fakt.

Raportimi i gjendjes më vonë

Kur elementi ekzekutohet, Skava dërgon dy vlera shtesë: callback_url dhe callback_token. Raportoni një gjendje të re aty më vonë dhe do të shfaqet një kartë e re në bisedë, edhe në telefon, ndërsa dikush po e sheh. E mëparshmeja mbetet, kështu që është e lexueshme se cila gjendje u raportua. Dërgoni të njëjtin objekt card si më lart, përmes POST me kryet Authorization: Bearer <callback_token>. Tri vlera opsionale vijnë pranë kartës:

• seq: numëruesi juaj. Një raport me vlerë më të vogël ose të barabartë hedhet poshtë, kështu që dy raporte nuk mund të tejkalojnë njëri-tjetrin.
• final: mbyll ndërveprimin. Tokeni bëhet i pavlefshëm dhe karta përfundon.
• notify: vendoseni në false për të publikuar kartën në heshtje, pa numër të paritë 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.

Një ndërveprim mund të publikojë më së shumti 50 karta. I njëjti raport dy herë nuk prodhon një kartë të dytë.

Skava përgjigjet me 200 dhe një listë hints nëse diçka është shkurtuar ose hedhur poshtë, dhe me 422 nëse karta ishte e papërdorshme. Një ndërveprim pranon raporte për 90 ditë.

Kartat postohen nga dërguesi i sistemit të Skava, jo nga personi që ekzekutoi elementin dhe jo nga një llogari e kompanisë suaj. Sistemi që shkruan përmendet në titullin e kartës.

Një shembull i plotë për t'u kopjuar gjendet në repozitorin nën example_order_server/ dhe ekzekutohet në api.skava.io.

Të lidhura

A dëshironi në vend të kësaj të ndërtoni një shabllon dokumenti të plotueshëm? Shihni Elementët e Përshtatur: Dokumentet.

Pyetjet e shpeshta