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.
Web programos API redaktorius su JSON raktimis ir formos ir JSON apžiūromis
API juodraštis rodo įvesties laukus su JSON raktimis bei formos ir JSON apžiūromis.
API juodraštis galo taškų skirtukas su URL ir metodu ir nelygintais žymimaisiais duomenimis
Demonstracinio juodraščio galo taškų skirtukas. Nurodomas paskirties adresas ir metodas; žymimieji duomenys nelyginti.

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ą.

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.

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ą.