Pasirinktiniai elementai: API

API sąsaja yra forma, kurios užpildytas reikšmes Skava JSON formatu siunčia jūsų nurodytu adresu (į jūsų backend). Taip saugiai susiejate Skava su savo sistemomis.

API sąsajos nustatymas

Sąsają sudaro įvesties laukai (jie sudaro JSON), paskirties adresas ir tapatybės nustatymas.

1. Sukurkite laukus: kiekvienas laukas gauna JSON raktą. Dešinėje realiuoju laiku matote JSON peržiūrą, kuri būtent taip siunčiama į jūsų backend.
2. Adresas (URL): jūsų backend https:// adresas. Leidžiami tik HTTPS adresai, pasiekiami viešai (žr. skyrių Saugumas žemiau).
3. Metodas: POST (numatytasis), PUT, PATCH arba GET. Su GET reikšmės pridedamos prie adreso kaip parametrai, o ne siunčiamos užklausos turinyje.
4. Tapatybės nustatymas: nurodykite antraštės pavadinimą (pavyzdžiui, Authorization) ir reikšmės priešdėlį (pavyzdžiui, Bearer ), tada išsaugokite tokeną. Pasirinktinai nustatykite galiojimo pabaigos datą.
5. Atsakymo laukai (nebūtina): keliu nurodykite, kurios reikšmės iš backend atsakymo rodomos, pavyzdžiui, order.id arba items[0].sku.
6. Patikrinkite su Ping ir Test Request, tada spauskite Paskelbti.

Saugus tokeno laikymas

Tokenas saugomas užšifruotas ir niekada negrąžinamas klientams: programa rodo tik tai, ar tokenas nustatytas ir kada baigiasi jo galiojimas. Siųsdama Skava jį serverio pusėje prideda prie nurodytos antraštės. Jei nustatėte galiojimo pabaigos datą, jai praėjus Skava iškvietimą atmeta ir paprašo tokeną atnaujinti.

Testavimas: Ping ir Test Request

• Ping yra lengvas pasiekiamumo patikrinimas. Jis tikrina tik tai, ar jūsų adresas atsako, ir tuo metu nesiunčia nei tokeno, nei formos duomenų. Rodo pasiekiamumą, būseną ir atsako laiką. Puikus pirmas žingsnis.
• Test Request yra tikras bandymas: siunčia jūsų adresu pavyzdinius duomenis kartu su tokenu ir parodo visą atsakymą bei išskirtus atsakymo laukus.

Kaip administratorius abu galite paleisti dar juodraščio stadijoje, kad patikrintumėte ryšį prieš paskelbdami.

Juodraštis ir paskelbimas

Kiekviena sąsaja iš pradžių yra juodraštis ir laisvai redaguojama. Kai viskas paruošta, ją paskelbiate mygtuku Paskelbti.

Saugumas

Kaip komanda naudoja paskelbtą sąsają

Kai sąsaja paskelbta, visi įmonės darbuotojai gali ją paleisti tiesiai iš pokalbio, redaktoriaus tam nereikia. Eiga tokia pati kaip su dokumentų šablonais: pasirinkti, užpildyti, išsiųsti.

1. Pokalbyje apačioje spustelėkite Pliusą ir pasirinkite Pasirinktinį elementą.
2. Iš sąrašo pasirinkite norimą šabloną arba sąsają.
3. Užpildykite formą ir spauskite Siųsti.
4. Rezultatas pokalbyje pasirodo kaip kortelė, matoma visiems pokalbio dalyviams.

Leiskite elementą sukurti dirbtiniam intelektui

Kaip įmonės administratoriui jums nebūtina pačiam naudotis redaktoriumi. Pasakykite tai Skava asistentui pokalbyje, pavyzdžiui: „sukurk man užsakymo formą pagal mano katalogą su kiekiu ir pristatymo adresu“. Iš to jis padaro juodraštį, vėliau gali keisti laukus po vieną ir žino jūsų įkeltą prekių katalogą: užsakymams jis siūlo prekių pasirinkiklį, o ne teksto lauką prekės numeriui.

Ką jis dar gali nustatyti: endpoint ir metodą, taip pat naudotojų ratą („tik įmonės darbuotojai“ arba „taip pat žmonės iš išorės tame pačiame pokalbyje“). Dėl naudotojų rato jis pirma paklausia, o ne tiesiog nustato, nes tai lemia, kas gali ką nors paleisti iš išorės.

Ko jis sąmoningai neliečia: prieigos tokeno. Jis niekada jo neprašo ir niekada nepriima, nes pokalbio žinutės yra saugomos. Jį patys įvedate redaktoriuje, kitaip nė vienas iškvietimas neišsiunčiamas. Ir jis negali paskelbti: paskutinis žingsnis lieka jums, todėl klientams niekas netampa matoma nepatikrinta.

Kas gali jį paleisti

Skirtukas „Endpoint“ nurodo, kas gali naudoti elementą. Numatytasis variantas yra jūsų įmonės darbuotojai. Antrasis nustatymas atveria jį ir žmonėms iš išorės, bet tik tame pokalbyje, kuriame dalyvauja ir kas nors iš jūsų įmonės, tai yra būtent tuo atveju, kuriam jis ir skirtas: klientas užsako pas jus. Kai jūsų įmonė išeina iš pokalbio, leidimas baigiasi savaime.

Prekės iš savo katalogo

Įkėlus savo prekių katalogą, kūrimo priemonė siūlo prekių pasirinkiklio bloką. Jokių parinkčių prižiūrėti nereikia: sąrašas yra jūsų katalogas. Užsakantis asmuo jame ieško, mato paveikslėlį, pavadinimą ir prekės numerį, o jūsų backend gauna prekės numerį. Numerį, kurio nėra jūsų kataloge, Skava atmeta. Kiekiui šalia įdėkite įprastą skaičiaus lauką.

Kortelę nusakykite patys

Ką kortelė sako, sprendžia jūsų backend. Skava tikrina tik formą, dydį ir saugumą, bet niekada prasmės: ji nežino nei užsakymų būsenų, nei laukų pavadinimų. Tam atsakykite objektu card:

{"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 nustatytas atsakymo susiejimas.
• state lemia tik spalvą ir piktogramą: ok, pending, warn arba error. Viskas, kas turi prasmę, keliauja į status_text kaip laisvas tekstas.
• fields yra etiketės ir reikšmės sąrašas, daugiausia 20 įrašų. Per ilgos reikšmės sutrumpinamos, o ne atmetamos, todėl užsakymas niekada nežlunga dėl smulkmenos.

Naudotojo įvesti duomenys priklauso serveriui: jie lieka nepaliesti, kad ir ką atsiųstų jūsų backend. Būtent jie pokalbyje užfiksuoja, kas iš tikrųjų buvo pateikta.

Būsenos pranešimas vėliau

Paleidus elementą, Skava atsiunčia dvi papildomas reikšmes: callback_url ir callback_token. Praneškite ten vėliau naują būseną, ir pokalbyje atsiras nauja kortelė, taip pat ir telefone, kol kas nors žiūri. Ankstesnė lieka, todėl matyti, kada kuri būsena buvo pranešta. Siųskite tą patį objektą card kaip aukščiau, metodu POST su antrašte Authorization: Bearer <callback_token>. Šalia kortelės galima nurodyti tris nebūtinas reikšmes:

• seq: jūsų pačių skaitiklis. Pranešimas su mažesne arba lygia reikšme atmetamas, todėl du pranešimai negali aplenkti vienas kito.
• final: užbaigia sąveiką. Tokenas nustoja galioti, o kortelė yra galutinė.
• notify: nustatykite false, kad kortelė būtų paskelbta tyliai, be neperskaitytų skaitiklio ir be pranešimo. Tarpiniams žingsniams, kurie neturi nieko žadinti. Be to kortelė yra visiškai įprasta žinutė.

Viena sąveika gali paskelbti daugiausia 50 kortelių. Tas pats pranešimas du kartus antros kortelės nesukuria.

Skava atsako kodu 200 ir sąrašu hints, jei kas nors buvo sutrumpinta ar praleista, ir kodu 422, jei kortelė buvo netinkama. Sąveika priima pranešimus 90 dienų.

Korteles skelbia Skava sisteminis siuntėjas, o ne žmogus, paleidęs elementą, ir ne jūsų įmonės paskyra. Kieno sistema rašo, nurodyta kortelės antraštėje.

Visas pavyzdys kopijavimui yra saugykloje, aplanke example_order_server/, ir veikia adresu api.skava.io.

Susiję

Ar vietoj to norite sukurti pildomą dokumento šabloną? Žiūrėkite Pasirinktiniai elementai: Dokumentai.

Dažnai užduodami klausimai