Elementet e personalizuara: API

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

Konfiguroni një ndërfaqe API

Një ndërfaqe përbëhet nga fusha hyrjeje (të cilat formojnë JSON), adresa e destinacionit 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. Adresa (URL): adresa https:// e backend-it tuaj. Lejoen vetëm adresa HTTPS dhe publike (shihni Sigurinë më poshtë).
3. Metoda: POST (parazgjedhje), PUT, PATCH ose GET. Me GET, vlerat shtohen si parametra pyetjeje në vend që të dërgohen në trup.
4. Autentifikimi: Vendosni emrin e kopshtit (p.sh. Authorization) dhe prefiksin e vlerës (p.sh. Bearer ), pastaj ruani token-in. Opsionalisht vendosni një datë skadence.
5. Fushat e përgjigjes (opsionale): Përcaktoni me rrugë cilat vlera nga përgjigja e backend-it duhen të shfaqen: p.sh. order.id ose items[0].sku.
6. Kontrolloni me Ping dhe Kërkesë Testi, pastaj Publikoni.

Ruajni token-in me siguri

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ërgohet, Skava e shton atë server-side në header-in e konfiguruar. Nëse vendosni një datë skadence, Skava e refuzon thirrjen pas skadencës dhe ju kërkon të rinovoni token-in.

Testim: Ping dhe Kërkesë Testi

• Ping: kontroll i thjeshtë i disponueshmërisë. Ai kontrollon vetëm se nëse adresa juaj përgjigjet, pa dërguar token ose të dhëna formulari gjatë procesit. Tregon disponueshmë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ë modalitet skicë për të verifikuar integrimin para lëshimit.

Përgatitje dhe Publikim

Çdo ndërfaqe fillon si bosht dhe mund të redaktohet lirë. Kur gjithçka është gati, e publikoni me Publiko.

Siguria

Si e përdor ekipi një ndërfaqe të publikuar

Sa herë që një ndërfaqe publikohet, të gjithë anëtarët e kompanisë mund ta aktivizojnë atë drejtpërdrejt nga biseda, pa nevojë për redaktor. Nuk ka hyrje kolektive dhe as dialog ndërmjetës: çdo element i publikuar ndodhet në menunë plus nën emrin e tij, me logon e kompanisë që e ofron.

1. Në bisedë, prek Plus poshtë dhe prek elementin që dëshiron, për shembull Komandë materiali.
2. Plotëso formularin dhe Dërgo.
3. Rezultati shfaqet si kartë në bisedë, i dukshëm për të gjithë në bisedë.

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

Si administrator i kompanisë, nuk duhet ta përdorni vetë editorin. Tregoni asistentin e Skavës në bisedë, për shembull "më ndërtë një formular porosi për katalogun tim me sasi dhe adresë dërgese". Ai krijon një boshtim nga kjo, mund të ndryshojë fushat një nga një më vonë, dhe njeh katalogun e artikujve që keni ngarkuar: për porosinë sugjeron zgjedhësin e produkteve në vend të një fushë 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ë jashtëm në të njëjtën bisedë"). Për audienca pyet fillimisht në vend që ta vendosë thjesht, sepse ajo përcakton kush mund të ekzekutojë diçka nga jashtë.

Çfarë nuk prek qartë: tokenin e aksesit. Ai kurrë nuk kërkon një dhe kurrë nuk pranon një, sepse mesazhet e bisedës ruhen. E vendosni vetë në editor, ndryshe asnjë thirrje nuk dilet. Dhe ai nuk mund ta publikojë: hapi i fundit mbetet te ju, kështu që asgjë nuk bëhet e dukshme për klientët pa u kontrolluar.

Kush mund ta ekzekutojë

Skeda "Endpoint" tregon kush mund të përdorë një element. Vlera e parazgjedhur janë anëtarët e kompanisë suaj. Cilësimi i dytë e hap atë për të jashtëm, por vetëm në një bisedë ku është i pranishëm dikush nga kompania juaj: saktësisht rasti për të cilin është menduar, klienti që porosit nga ju. Kur kompania juaj largohet nga biseda, leja mbaron vetë.

Produktet nga katalogu juaj

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

Përcaktoni kartën vetë

Backend-i juaj vendos se çfarë thotë karta. Skava kontrollojë vetëm formën, madhësinë dhe sigurinë, kurrë kuptimin: ajo nuk e di as gjendjet e porosisë, 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 aplikohet hartimi i përgjigjes i konfiguruar në element.
• state përfshin vetëm ngjyrën dhe ikonën: ok, pending, warn ose error. Çdo gjë që ka kuptim shkon në status_text si tekst i lirë.
• fields është një listë me etiketa dhe vlera, me maksimum 20 hyrje. Vlerat shumë të gjata shkurtohen në vend që të refuzohen, kështu që një porosi nuk dështon për shkak të një detaji.

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

Raportimi i statusit 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 një kartë e re shfaqet në bisedë, edhe në telefon, ndërsa dikush po e shikon. E mëparshmba mbetet, kështu që lexohet qartë se cila gjendje u raportua. Dërgoni të njëjtin objekt card si më lart, përmes POST me kryesoren Authorization: Bearer <callback_token>. Tre vlera opsionale shkojnë pranë kartës:

• 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.
• final: mbyll ndërveprimin. Tokeni bëhet i pavlefshëm dhe karta bëhet përfundimtare.
• notify: vendoseni si false për të postuar kartën në heshtje, pa numër të pa lexuara dhe pa njoftim. Për hapa të mesëm që nuk duhet të zgjojnë askënd. Pa këtë, karta është një mesazh plotësisht i zakonshëm.

Një ndërveprim mund të postojë deri në 50 karta. Dy herë i njëjti raport nuk prodhon një kartë të dytë.

Skava përgjigjet me 200 dhe një listë hints nëse diçka u shkurtua ose u la anash, 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 i cili po 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

Dëshironi të ndërtoni një model dokumenti të plotueshëm? Shihni Elementë të personalizuar: Dokumente.

Pyetjet më të shpeshta