Kohandatud elemendid: API

API-liides on vorm, mille täidetud väärtused saadab Skava JSON-i kujul sulle määratud aadressile (sinu tagasüsteemile). Nii saad Skava turvaliselt oma süsteemidega ühendada.

API-liidese seadistamine

Liides koosneb sisendväljadest (moodustavad JSON-i), sihtasust ja autentimisest.

1. Loo väljad: Igal väljal on oma JSON-ki. Paremal näete JSON-eelvaadet reaalajas, mis saadetakse teie tagaküljele täpselt selles vormis.
2. Aadress (URL): teie tagakülje https:// aadress. Luba ainult HTTPS ja avalikult ligipääsetavad aadressid (vt allpool jaotist Turvalisus).
3. Meetod: POST (vaikimisi), PUT, PATCH või GET. GET korral lisatakse väärtused päringuparameetriteks, mitte saadetud kehasse.
4. Autentimine: Määra päise nimi (nt Authorization) ja väärtuse eesliide (nt Bearer ), seejärel salvesta token. Valikuline: määra aegumisaeg.
5. Vastuse väljad (valikuline): Määra tee, millised väärtused tagakülje vastuses kuvatakse: nt order.id või items[0].sku.
6. Kontrolli Ping ja Test Request, seejärel Release.

Salvesta token turvaliselt

Token salvestatakse krüpteerituna ja ei tagastata kunagi klientidele: rakendus näitab ainult kas token on seadistatud ja millal see aegub. Saatmisel lisab Skava selle serveri poolt seadistatud päisesse. Kui määratled aegumiskuupäeva, keeldub Skava aegumise järel helistusest ja küsib, et uuendaksid tokeni.

Testimine: Ping ja Test Request

• Ping: kerge saadavuse kontroll. See kontrollib ainult kas teie aadress reageerib, ilma et saadetaks tokenit või vormiandmeid. Näitab saadavust, olekut ja vastusaja. Ideaalne esimese sammu tegemiseks.
• Testipäring: tegelik proovijooks: saadab teie aadressile näidisandmed, sealhulgas tokeni ja näitab nii täielikku vastust kui ka väljastatud vastusvälju.

A administraatorina saate mõlemad teha veel mustandis, et kontrollida integratsiooni enne avaldamist.

Mustand ja avaldamine

Iga liides algab mustandina 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 selle otse vestlusest käivitada, ilma redaktori kasutamiseta. Kollektiivset sissemärkumist ega vahepealset dialoogi ei ole: iga avaldatud element asub plahmenüüs oma nime all koos pakkuva ettevõtte logoga.

1. Vestluses puuduta alumisel ribal Pluss ja vali soovitud element, näiteks Materjalide tellimus.
2. Täida vorm ja vajuta Saada.
3. Tulemus ilmub vestluses kaardina, mis on nähtav kõigile vestluses osalejatele.

Lase AI-l luua element

Ettevõtte administraatorina ei pea sa redaktorit ise kasutama. Räägi Skava assistendile vestluses näiteks „tee mulle tellimuse vormi minu kaupa jaoks koguse ja tarneaadressiga”. See loob sellest mustandi, suudab hiljem välju ükshaaval muuta ja tunneb sinu üleslaetud kaubakataloogi: tellimuste puhul soovitab see tootevalikut, mitte tekstivälja artiklinumbrile.

See võib seada ka: lõpppunkti ja meetodi ning sihtgrupi („ainult ettevõtte liikmed” või „ka välised isikud samas vestluses”). Sihtgrupi puhul küsib see esmalt, mitte seab seda kohe, sest see määrab, kes võib midagi väljastpoolt käivitada.

Mida see selgelt ei puuduta: juurdepääsuvõtit. See ei küsi seda kunagi ega võta seda vastu, sest vestlus sõnumeid salvestatakse. Sisestad selle ise redaktoris, muidu ei lähe ükski päring välja. Ja see ei saa avaldada: viimane samm jääb sulle, et midagi ei muutuks klientidele nähtavaks kontrollimata.

Kes võib seda käivitada

Vaade „Lõpppunkt” näitab, kes võib elementi kasutada. Vaikimisi on see sinu ettevõtte liikmed. Teine seade avab selle välisistele, aga ainult vestluses, kus on ka sinu ettevõtte liige: täpselt see juhtum, milleks see on mõeldud, kui klient teilt tellib. Kui sinu ettevõte vestlusest lahkub, lõpeb õigus iseendast.

Tooted oma kataloogist

Pärast artiklite kataloogi üleslaadimist pakub ehitaja tootevalija blokki. Valikuid pole vaja haldada: loetelu on sinu kataloog. Tellija otsib sealt, näeb pildi, nime ja artiklinumbri ning sinu tagakont saab artiklinumbri. Skava lükkab tagasi numbri, mis pole sinu kataloogis. Koguse jaoks pane selle kõrvale tavaline numberväli.

Määra kaart ise

Sinu tagakont otsustab, mida kaart ütleb. Skava kontrollib ainult kuju, suurust ja turvalisust, mitte sisu: see ei tea tellimuse olekuid ega väljanimi. Selleks vasta 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 määratud vastuse kaardistus.
• state on ainult värv ja ikoon: ok, pending, warn või error. Kõik, mis kannab sisu, sisestatakse vabana tekstina väljundisse status_text.
• fields on nime ja väärtuse loetelu, maksimaalselt 20 kirjet. Liiga pikad väärtused lühendatakse, mitte keelatakse, et tellimus ei ebaõnnuks üksikasja pärast.

Kasutaja sisestused kuuluvad serverile: need jäävad puutumata, olenemata sellest, mida teie tagakontuur saadab. Need on vestluses salvestus sellest, mis tegelikult esitati.

Staadi hilisem teavitamine

Kui element käivitub, saadab Skava kaks lisaväärtust: callback_url ja callback_token. Teatage hiljem uuest staadist seal ja vestluses, ka telefonis, kui keegi seda vaatab, ilmub uus kaart. Eelmine kaart jääb alles, et oleks loetav, milline staat teatati. Saadage sama card objekt kui eelnevalt, kasutades POST päringut päisega Authorization: Bearer <callback_token>. Kolm valikulist väärtust asuvad kaardi kõrval:

• seq: oma loendur. Raport, mille väärtus on väiksem või võrdne, heidetakse maha, nii et kaks raporti ei saa üksteist ületada.
• final: lõpetab interaktsiooni. Token muutub kehtetuks ja kaart on lõplik.
• notify: määra väärtuseks false, et postitada kaart vaikselt, ilma lugemata loendurita ja teavitusteta. Sobib vaheetappide jaoks, mis ei tohiksid kedagi ärata. Ilma selle parameetrita on kaart täiesti tavaline sõnum.

Üks interaktsioon võib postitada maksimaalselt 50 kaarti. Sama rapordi kordamine ei loo teist kaarti.

Skava vastab koodiga 200 ja loendiga hints, kui midagi lühendati või heideti maha, ning koodiga 422, kui kaart oli kasutamiskõlbmatu. Interaktsioon aktsepteerib raporte 90 päeva.

Kaardid postitatakse Skava süsteemi saatja poolt, mitte selle inimese poolt, kes elementi käivitas, ega teie ettevõtte kontoga. Kaardi pealkirjas on märgitud, kumma süsteemi poolt see on kirjutatud.

Täielik näidis, mida saab kopeerida, asub repooris kausta example_order_server/ all ja töötab aadressil api.skava.io.

Seotud

Kas soovite hoopis luua täidetava dokumendimalli? Vaadake Kohandatud elemendid: Dokumendid.

Korduma kippuvad küsimused