Kohandatud elemendid: API

API-liides on vorm, mille täidetud väärtusi Skava saadab JSON-vormingus teie määratud aadressile (teie tagasüsteemile). Sel viisil saate Skava turvaliselt ühendada oma süsteemidega.

Seadistage API-liides

Liides koosneb sisendväljadest (need moodustavad JSON-i), siht-aadressist ja autentimisest.

1. Väljade loomine: Iga väli saab JSON- võtme. Paremal näete otse JSON-eelvaadet, mis saadetakse teie backendile täpselt sel viisil.
2. Aadress (URL): teie backendi https:// aadress. Lubatud on ainult HTTPS ja avalikult ligipääsetavad aadressid (vt allpool jaotist Turvalisus).
3. Meetod: POST (vaikimisi), PUT, PATCH või GET. GET puhul lisatakse väärtused päringuparameetritena, mitte saadetakse kehas.
4. Autentimine: Määrake päise nimi (nt Authorization) ja väärtuse eesliide (nt Bearer ), seejärel salvestage token. Vajaduse korral määrake aegumiskuupäev.
5. Vastuse väljad (valikuline): Määrake tee järgi, millised väärtused backendi vastusest kuvatakse: nt order.id või items[0].sku.
6. Kontrollige Ping ja Test Request abil, seejärel Release.

Salvestage token turvaliselt

Token salvestatakse krüptituna ja ei tagastata kunagi klientidele: rakendus näitab ainult, kas token on määratud ja millal see aegub. Saatmisel lisab Skava selle serveri poolel määratletud päisesse. Kui määrate aegumiskuupäeva, keeldub Skava aegumise järel kõnest ja palub teil token uuendada.

Testimine: Ping ja Test Request

• Ping : kerge saavutatavuse kontroll. See kontrollib ainult kas teie aadress vastab, ja ei saata protsessi käigus tokenit ega vormi andmeid. Näitab saavutatavust, staatust ja vasteaega. Ideaalne esimeseks sammuks.
• Testi taotlus : tegelik katsejooks: saadab teie aadressile prooviandmed, sealhulgas tokeni, ja näitab teile täielikku vastust ning välja tõmmatud vastuse välju.

Adminina saate mõlemat käivitada veel mustandirežiimis, et kontrollida integreerimist enne avaldamist.

Mustand ja avaldamine

Iga liides algab kui mustand ja seda saab vabalt muuta. Kui kõik on valmis, avaldate selle nupuga Avalda.

Turvalisus

Kuidas meeskond kasutab avaldatud liidest

Pärast liidese avaldamist saavad kõik ettevõtte liikmed seda otse vestlusest käivitada : redaktorit ei ole vaja. Vool on sama nagu dokumandimallide puhul: vali, täida, saada.

1. Vestluses vajutage allpool nuppu Pluss ja valige Kohandatud element.
2. Valige loendist soovitud mall või liides.
3. Täitke vorm ja vajutage Saada.
4. Tulemus ilmub vestluses kaardina: nähtav kõigile vestluses osalejatele.

Luba AI-l luua element

Ettevõtte administraatorina ei pea te redaktorit ise kasutama. Ütlege Skava abile vestluses näiteks „loo mulle tellimusvorm oma kataloogiga koguse ja kohaletoimetamise aadressiga". See loob sellest mustandi, hiljem saab väljaid ükshaaval muuta ning see teab teie üleslaaditud artiklite kataloogi: tellimuste puhul pakutakse tootevalikut, mitte tekstivälja artiklinumbrile.

Mida see veel seadistada võib: lõpp-punkti ja meetodi ning sihtrühma („ainult ettevõtte liikmed" või „ka välised isikud samas vestluses"). Sihtrühma puhul küsib see esmalt, mitte ei seadista kohe, kuna see otsustab, kes võib midagi väljastpoolt käivitada.

Mida see selgelt ei puutu: juurdepääsupiirangut. See ei küsi seda kunagi ega aktsepteeri seda, kuna vestlusviisad salvestatakse. Sisestate selle ise redaktoris, muidu ei lähe ükski kõne välja. Ja see ei saa avaldada: viimane samm jääb teie kätte, et midagi kontrollimata klientidele nähtavaks ei muutuks.

Kes seda kasutada võib

Vahekaart „Lõpp-punkt" näitab, kes elementi kasutada võib. Vaikimisi on see teie ettevõtte liikmed. Teine seade avab selle välisile isikutele, kuid ainult vestluses, kus on ka teie ettevõtte liige: täpselt see juhtum, milleks see on mõeldud, kui klient teilt tellib. Kui teie ettevõte vestlusest lahkub, lõpeb luba automaatselt.

Tooteid oma kataloogist

Pärast tootekataloogi üleslaadimist pakub looja tootevaliku ploki. Seadistusi pole: nimekiri on teie kataloog. Tellija otsib seda, näeb pilti, nime ja artiklinumbrit ning teie backend saab artiklinumbri. Skava lükkab tagasi numbri, mis ei ole teie kataloogis. Hulguse jaoks asetage selle kõrvale tavaline arvuväli.

Määrake kaart ise

Teie backend otsustab, mida kaart ütleb. Skava kontrollib ainult kuju, suurust ja turvalisust, mitte tähendust: ta ei tea tellimuse seisunditest ega väljanimedest. Selleks vastake card objektiga:

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

• v peab olema täisarv 1. Ilma selleta ei loeta vastust kaardiks ja kehtib elemendis konfigureeritud vastuse kaardistamine.
• state on määrab ainult värvi ja ikooni: ok, pending, warn või error. Kõik sisuline teave sisestatakse vabatekstina väljale status_text.
• fields on nimekirja siltidest ja väärtustest, maksimaalselt 20 kirjet. Liiga pikad väärtused lühendatakse, mitte tagasi lükatakse, et tellimus ei ebaõnnestu üksikasjade tõttu.

Kasutaja sisendid kuuluvad serverile: need jäävad muutumatuks sõltumata sellest, mida teie backend saadab. Need on vestluse logis salvestatud andmed selle kohta, mis tegelikult esitati.

Olekute hilisem teatamine

Kui element käivitub, saadab Skava kaks lisaväärtust: callback_url ja callback_token. Saadke hiljem uue oleku teade sellele aadressile, et vestluses ja telefonis ilmus uus kaart, isegi kui keegi seda just vaatab. Eelmine kaart jääb alles, et oleks näha, millist olekut teatati. Saadke sama card objekt kui ülal, kasutades POST päringut päisega Authorization: Bearer <callback_token>. Kaardi juurde lisatakse kolm vabatahtlikku väärtust:

• seq: oma loendur. Aruanne, mille väärtus on väiksem või võrdne, jäetakse tähelepanuta, seega ei saa kaks aruannet teineteist ületada.
• final: lõpetab interaktsiooni. Token muutub kehtetuks ja kaart on lõplik.
• notify: määra väärtuseks false, et postitada kaart vaikimisi ilma loetud lugemata ja teavitusteta. See sobib vaheastmete jaoks, mis ei tohiks kedagi ärkama panna. Ilma selleta on kaart täiesti tavaline sõnum.

Interaktsioon võib postitada maksimaalselt 50 kaarti. Sama aruande esitamine kaks korda ei teki teist kaarti.

Skava vastab koodiga 200 ja hints loendiga, kui midagi lühendati või jäeti välja, ning koodiga 422, kui kaart oli kasutuskõlbmatu. Interaktsioon aktsepteerib aruandeid 90 päeva jooksul.

Kaardid postitab Skava süsteemi saatja, mitte isik, kes elementi käivitas, ega teie ettevõtte konto. Kelle süsteem kirjutab, on näidatud kaardi pealkirjas.

Täielik näide, mida kopeerida, asub hoidlas asukohas example_order_server/ ja töötab aadressil api.skava.io.

Seotud

Kas soovite hoopis luua täidetavat dokumendimall? Vaadake Kohandatavad elemendid: dokumendid.

Sagedased küsimused