Skava Skava / Wiki

Pritaikyti elementai: API

API sąsaja yra forma, kurios užpildytos reikšmės Skava siunčia JSON formatu į nurodytą adresą (jūsų backend). Taip galite saugiai sujungti Skava su savo sistemomis.

i

API sąsajas valdote Webapp skiltyje Custom Elements → įjunkite API Interfaces. Kūrimas ir redagavimas skirtas company admins; paskelbtas sąsajas gali aktyvuoti visi įmonės nariai.

Sukurkite API sąsają

Sąsaja susideda iš įvesties laukų (jie sudaro JSON), tikslinio adreso ir autentifikacijos.

  1. Sukurkite laukus: Kiekvienas laukas turi JSON raktą. Dešinėje matote JSON peržiūrą, kuri taip pat siunčiama į jūsų backendą.
  2. Adresas (URL): jūsų backendo https:// adresas. Leidžiami tik HTTPS ir viešai prieinami adresai (žr. Saugumą žemiau).
  3. Metodas: POST (numatyta), PUT, PATCH arba GET. Naudojant GET, reikšmės pridedamos kaip užklausos parametrai, o ne siunčiamos kūne.
  4. Autentifikacija: Nurodykite antraštės pavadinimą (pvz., Authorization) ir reikšmės prefiksą (pvz., Bearer ), tada išsaugokite žetoną. Pasirinktinai nustatykite galiojimo pabaigos datą.
  5. Atsakymo laukai (neprivaloma): Nurodykite kelią, kad būtų rodomos backendo atsakymo reikšmės: pvz., order.id arba items[0].sku.
  6. Patikrinkite su Ping ir Test Request, tada Release.
Skava naršyklės programėlė: API sąsajos „Laukai“ skirtukas. Viršuje automatiškai įtraukiamos konteksto reikšmės (vartotojo vardas, įmonė, projektas …), žemiau – su JSON raktais žymimi specialieji laukai, dešinėje – formos ir gyvo JSON peržiūra.
Laukų skirtukas: kiekvienas laukas gauna JSON raktą. Viršuje automatiškai įtraukiamos konteksto reikšmės, pvz., vartotojas, įmonė ir projekto pavadinimas. Dešinėje matote formą ir gyvą JSON: būtent tai, kas siunčiama į jūsų backendą.
Skava naršyklės programėlė: API sąsajos „Endpoint“ skirtukas su URL, POST metodo, laukimo laiko, autentifikacijos antraštės, Bearer reikšmės prefikso ir šifruoto žetono įvedimo laukais.
Endpoint skirtukas: tikslinis adresas (tik HTTPS), metodas, laukimo laikas bei autentifikacijos antraštė su reikšmės prefiksu. Žetonas saugomas šifruota ir niekada nesiunčiamas klientams.
Skava naršyklės programėlė: API sąsajos peržiūros skirtukas. Nustatytas atsakymo laukas su JSON raktu Success, dešinėje matoma peržiūra, kaip rezultatas atrodys pokalbyje.
Peržiūros skirtukas (neprivalomas): nurodykite kelią, pagal kurį iš backend atsakymo rodomos reikšmės. Dešinėje Skava iš jų sudaro rezultatų kortelę, tiksliai taip, kaip ji vėliau pasirodys pokalbyje.

Saugiai saugokite žetoną

Žetonas saugomas šifruotai ir niekada negrąžinamas klientams: programėlė rodo tik ar žetonas nustatytas ir kada jis baigia galioti. Siunčiant, Skava serverio pusėje prideda jį prie nustatyto antraštinio lauko. Jei nustatote galiojimo pabaigos datą, po jos praeinimo Skava atmeta kvietimą ir prašo atnaujinti žetoną.

Testavimas: Ping ir Test Request

  • Ping: lengva pasiekiamumo patikra. Ji tikrina ar jūsų adresas reaguoja ir neskelbia tokeno ar formos duomenų. Rodo pasiekiamumą, būseną ir atsakymo laiką. Tinka kaip pirmas žingsnis.
  • Test Request: tikras bandymas: siunčia pavyzdinius duomenis, įskaitant tokeną, į jūsų adresą ir rodo pilną atsakymą bei išgautus atsakymo laukus.

Būdami administratoriumi, galite vykdyti abu veiksmus dar brėžinio režime, kad patikrintumėte integraciją prieš paleidimą.

Skava webapp: API sąsajos Test skirtukas su Ping ir Test Request mygtukais, rezultatu Status 200 OK, atsakymo laiku ir pilnu JSON atsakymu iš backend.
Test skirtukas: Ping ir Test Request šalia vienas kito. Čia su 200 būsenos kodu, atsakymo laiku ir pilnu backend atsakymu JSON formatu.

Juodraštis ir leidimas

Kiekviena sąsaja prasideda kaip juodraštis ir gali būti laisvai redaguojama. Kai viskas paruošta, ją leidžiate paspaudę Leisti.

!

Po leidimo tikslinis adresas, metodas, laukai, autentifikacijos antraštė ir laiko riba yra fiksuojami. Tai daryta sąmoningai: niekas negali tyliai pakeisti, kur siunčiami duomenys. Tik trys dalykai lieka keičiami, nes operacijoms jų reikia: žetono ir jo galiojimo pabaigos (kad pasibaigusio ar sugadinto žetono būtų galima pakeisti) bei auditorija, tai yra, ar sąsają gali paleisti tik jūsų komanda, ar ir partnerių įmonės pokalbyje. Visam kitam sukuriate naują versiją.

Saugumas

i

Kad sąsaja nebūtų piktnaudžiavama, galioja griežtos taisyklės: leidžiami tik HTTPS adresai, o adresas turi nurodyti viešą tikslinį adresą: vidiniai adresai (pvz., localhost, privačios tinklai arba debesies metaduomenys) yra atmetami. Skava tai tikrina kiekvieno kvietimo metu, jungiasi tik prie patikrinto adreso, neina per peradresacijas ir riboja laukimo laiką bei atsakymo dydį.

Kaip komanda naudoja paskelbtą sąsają

Kai sąsaja yra paskelbta, visi įmonės nariai gali ją tiesiogiai aktyvuoti iš pokalbio, nereikia redaktoriaus. Nėra bendro įrašymo ir tarpinio dialogo: kiekviena paskelbta elementas yra plius meniu po savo pavadinimu, su jį teikiančios įmonės logotipu.

  1. Pokalbyje palieskite Plius apačioje ir palieskite norimą elementą, pavyzdžiui, Medžiagų užsakymas.
  2. Užpildykite formą ir paspauskite Siųsti.
  3. Rezultatas pasirodo kaip kortelė pokalbyje, matoma visiems pokalbio dalyviams.
Skava naršyklės programėlė: API veiksmo „Medžiagų užsakymas“ užpildoma forma su laukais: prekių numeris, aprašymas, kiekis, matavimo vienetas, pageidaujama pristatymo data ir pastaba, taip pat pastaba apie automatiškai įtraukiamas reikšmes.
3 žingsnis: užpildykite formą. Apačioje esanti pastaba rodo, kurios reikšmės įtraukiamos automatiškai.
Skava naršyklės programėlė: API veiksmo „Medžiagų užsakymas“ rezultato kortelė pokalbyje su būsena 200, įvestomis reikšmėmis ir galinės dalies atsakymu (užsakymo numeris, būsena, pristatymo data), taip pat išskleidžiamos žaliavos duomenys.
4 žingsnis: pokalbyje esanti rezultato kortelė su įvestimis ir jūsų galinės dalies atsakymu.

Leiskite dirbtiniam intelektui sukurti elementą

Būdami įmonės administratoriumi, jums nereikia naudoti redaktoriaus. Paprašykite Skava asistentės pokalbyje, pavyzdžiui, „sukurk užsakymo formą mano katalogui su kiekiu ir pristatymo adresu“. Ji iš to sudaro juodraštį, vėliau gali keisti laukus po vieną ir žino jūsų įkeltą prekių katalogą: užsakymams ji siūlo prekių pasirinkiklį, o ne teksto lauką prekių numeriui.

Ji taip pat gali nustatyti: galutinį tašką ir metodą bei auditoriją („tik įmonės nariai“ arba „ir pašaliniai asmenys tame pačiame pokalbyje“). Dėl auditorijos ji pirmiausia klausia, o ne tiesiog nustato, nes tai lemia, kas gali vykdyti veiksmus iš išorės.

Ko ji aiškiai neliečia: prieigos rakto. Ji niekada jo neklausia ir niekada jo nepriima, nes pokalbio žinutės yra saugomos. Jį įvedate patys redaktoriuje, kitaip joks kvietimas neišsiunčiamas. Ji taip pat negali publikuoti: paskutinis žingsnis lieka jums, todėl nieko nepastebėto klientams nematoma.

Kas gali tai vykdyti

Skiltyje „Galutinis taškas“ nurodoma, kas gali naudoti elementą. Numatyta, kad tai jūsų įmonės nariai. Antrasis nustatymas atidaro prieigą pašaliniams asmenims, bet tik pokalbyje, kuriame yra ir jūsų įmonės atstovas: būtent tai atvejis, kuriam tai skirta, kai klientas užsako pas jus. Kai jūsų įmonė palieka pokalbį, leidimas baigiasi savaime.

Prekės iš jūsų katalogo

Kai įkeliate savo prekių katalogą, statytojui siūlomas prekių pasirinkimo blokas. Nėra jokių nustatymų, kuriuos reikėtų prižiūrėti: sąrašas yra jūsų katalogas. Užsakantis asmuo jį ieško, mato vaizdą, pavadinimą ir prekių numerį, o jūsų backendas gauna prekių numerį. Skava atmeta numerį, kurio nėra jūsų kataloge. Kiekiaiui įrašykite įprastą skaičių lauką šalia.

Kortelę apibrėžkite patys

Jūsų backendas nusprendžia, ką kortelė sako. Skava tikrina tik formą, dydį ir saugumą, niekada prasmę: ji nežino nei užsakymų būsenų, nei laukų pavadinimų. Tam atsakykite card objektu:

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

  • v turi būti sveikasis skaičius 1. Be jo atsakymas nelaikomas kortele ir taikomas elemente sukonfigūruotas atsakymo atvaizdavimas.
  • state yra tik spalva ir ikona: ok, pending, warn arba error. Visas prasmės turinčias dalis įrašykite į status_text kaip laisvą tekstą.
  • fields yra žymos ir reikšmių sąrašas, daugiausia 20 įrašų. Per ilgos reikšmės sutrumpinamos, o ne atmestos, todėl užsakymas niekada nepavyksta dėl smulkmenos.

Vartotojo įvestys priklauso serveriui: jos lieka nepaliestos, nepriklausomai nuo to, ką siunčia jūsų backendas. Jos yra pokalbio įrašas apie tai, kas iš tikrųjų buvo pateikta.

Būsena pranešimas vėliau

Kai elementas veikia, Skava siunčia dvi papildomas reikšmes: callback_url ir callback_token. Vėliau ten praneškite naują būseną ir pokalbyje, taip pat telefone, pasirodys nauja kortelė, kai kas nors žiūri. Ankstesnė lieka, todėl matyti, kuri būsena buvo pranešta. Siųskite tą patį card objektą kaip aukščiau, per POST su antrašte Authorization: Bearer <callback_token>. Trys nepriklausomos reikšmės eina šalia kortelės:

  • seq: jūsų skaičiuoklė. Ataskaita su mažesne arba lygia reikšme yra atmesta, todėl dvi ataskaitos negali viena kitos aplenkti.
  • final: užbaigia sąveiką. Žetonas tampa nebevalidus, o kortelė tampa galutinė.
  • notify: nustatykite false, kad kortelė būtų paskelbta tyliai, be neskaitytų žinučių skaičiaus ir be pranešimo. Tinka tarpiniams žingsniams, kurie neturėtų pabudinti nieko. Be šio parametrio kortelė yra visiškai įprasta žinutė.

Sąveika gali paskelbti daugiausiai 50 kortelių. Tas pats ataskaitos du kartus nepasikartojimas nesukelia antros kortelės.

Skava atsako 200 ir hints sąrašu, jei kas nors buvo sutrumpinta arba atmesta, bei 422, jei kortelė buvo netinkama. Sąveika priima ataskaitas 90 dienų.

Kortelę siunčia Skava sistemos siuntėjas, o ne asmuo, kuris paleido elementą, ir ne jūsų įmonės paskyra. Kortelės pavadinime nurodyta, kurios sistemos tai yra.

Pilnas pavyzdys, kurį galima nukopijuoti, yra saugyklos kataloge example_order_server/ ir veikia adresu api.skava.io.

Susiję

Ar norite sukurti užpildomą dokumento šabloną? Žr. Custom Elements: Dokumentai.

Dažniausiai užduodami klausimai

Kas yra API sąsaja Skava?

Forma, kurios užpildytos reikšmės Skava siunčia JSON formatu į nurodytą adresą (jūsų backendą): patogu sujungti Skava su savo sistemomis.

Kas gali kurti ir aktyvuoti API sąsajas?

Kūrimas ir redagavimas skirtas įmonės administratoriams. Paskelbtą sąsają gali aktyvuoti visi įmonės nariai.

Koks skirtumas tarp „Ping“ ir „Test Request“?

Ping tikrina, ar adresas pasiekiamas: be žetono ir be duomenų. Test Request siunčia pavyzdinius duomenis, įskaitant žetoną, ir rodo pilną atsakymą.

Ar mano API žetonas saugus?

Taip. Žetonas saugomas šifruotas ir niekada neskelbiamas klientams. Programėlė rodo tik tai, ar žetonas nustatytas, ir kada jis baigia galioti.

Kokie adresai leidžiami kaip galiniai taškai?

Tik viešai prieinami https:// adresai. Vidiniai tikslai, tokie kaip localhost, privatus tinklas ar debesies metaduomenys, yra atmetami: taip apsaugoma nuo sąsajos piktnaudžiavimo.

Kodėl negaliu keisti išleisto sąsajos?

Tikslinis adresas, metodas, laukai ir autentifikacijos antraštė po išleidimo yra fiksuoti, todėl niekas negali tyliai pakeisti, kur siunčiami duomenys. Žetonas, jo galiojimo laikas ir auditorija (tik savo komanda arba ir partnerių įmonės) lieka keičiami; būtent taip pakeičiate pasibaigusį žetoną. Visam kitam sukuriate naują versiją.