Mukautetut alkiot: API

API-liittymä on lomake, jonka täytetyt arvot Skava lähettää JSON-muodossa määrittämääsi osoitteeseen (omalle palvelimellesi). Tällä tavalla voit yhdistää Skavan turvallisesti omiin järjestelmiisi.

Määritä API-liittymä

Liittymä koostuu syöttökentistä (ne muodostavat JSONin), kohdeosoitteesta ja tunnistautumisesta.

1. Kenttien luominen: Jokaiselle kentälle annetaan JSON-avain. Oikealla näkyy JSON-esikatselu reaaliajassa, ja se lähetetään takapääsi tällaisena.
2. Osoite (URL): takapääsi osoite, joka alkaa https://-etuliitteellä. Vain HTTPS-osoitteet ja julkisesti saatavilla olevat osoitteet ovat sallittuja (ks. Turvallisuus alla).
3. Menetelmä: POST (oletus), PUT, PATCH tai GET. GET-menetelmällä arvot lisätään kyselyparametreina sen sijaan, että niitä lähetettäisiin viestin rungossa.
4. Hyväksyntä: Määritä otsikon nimi (esim. Authorization) ja arvon etuliite (esim. Bearer ), ja tallenna token. Voit halutessasi asettaa myös vanhenemisajankohdan.
5. Vastauskentät (valinnainen): Määritä polun avulla, mitkä arvot takapään vastauksesta näytetään: esim. order.id tai items[0].sku.
6. Tarkista Ping- ja Test Request-toiminnoilla, sitten Release.

Säilytä token turvallisesti

Token säilytetään salattuna eikä sitä koskaan palauteta asiakkaille: sovellus näyttää vain onko token määritetty ja milloin se vanhenee. Lähetettäessä Skava lisää sen palvelinpohjaisesti määritettyyn otsikkoon. Jos asetat vanhenemisajankohdan, Skava hylkää kutsun vanhenemisen jälkeen ja pyytää uutta tokenia.

Testaus: Ping ja Test Request

• Ping : kevyt saavutettavuustesti. Se tarkistaa vain vastaaako osoitteesi, eikä lähetä tokenia tai lomake tietoja. Näyttää saavutettavuuden, tilan ja vasteajan. Sopii ensisijaiseksi vaiheeksi.
• Koe pyyntö : todellinen koeajo: lähettää otosdataa mukaan lukien token osoitteeseesi ja näyttää täydellisen vastauksen sekä eritellyt vastauskentät.

Ylläpitäjänä voit suorittaa molemmat vielä luonnos tilassa varmistaaksesi integraation ennen julkaisua.

Luonnos ja julkaisu

Jokainen käyttöliittymä alkaa luonnoksena, jota voi muokata vapaasti. Kun kaikki on valmista, julkaiset sen painamalla Julkaise.

Turvallisuus

Miten tiimi käyttää julkaistua rajapintaa

Kun rajapinta on julkaistu, kaikki yrityksen jäsenet voivat käynnistää sen suoraan keskustelusta: muokkausnäkymää ei tarvita. Toimintatapa on sama kuin asiakirjapohjien kanssa: valitse, täytä, lähetä.

1. Keskustelussa paina alareunassa olevaa Plus-painiketta ja valitse Mukautettu elementti.
2. Valitse haluamasi pohja tai rajapinta listasta.
3. Täytä lomake ja Lähetä.
4. Tulos näkyy viestikeskustelussa korttina : kaikkien keskustelun osallistujien nähtävissä.

Anna tekoälyn luoda elementti

Yrityksen ylläpitäjänä sinun ei tarvitse käyttää muokkainta itse. Kerro Skava-assistentille chatissa esimerkiksi "luo minulle tilauslomake tuotekatalogiini, jossa on määrä ja toimitusosoite". Se luo siitä luonnoksen, jota voi myöhemmin muuttaa kenttä kerrallaan, ja se tuntee lataamasi tuotekatalogin: tilauksissa se ehdottaa tuotteen valitsijaa artikkelinumeron tekstikentän sijaan.

Mitä se voi myös asettaa: päätepisteen ja metodin sekä yleisön ("vain yrityksen jäsenet" tai "myös samassa chatissa olevat ulkopuoliset"). Yleisön osalta se kysyy ensin sen sijaan, että asettaisi sen suoraan, koska se päättää, kuka voi suorittaa jotain ulkopuolelta.

Mitä se ei kosketa: käyttöoikeustunnisteen. Se ei koskaan pyydä sitä eikä hyväksy sitä, koska chat-viestit tallennetaan. Syötät sen itse muokkainnissa, muuten kutsua ei lähetetä. Ja se ei voi julkaista: viimeinen vaihe jää sinun tehtäväksesi, jotta mitään ei tule näkyville asiakkaille tarkistamattomana.

Kuka voi suorittaa sen

"Päätepiste"-välilehti kertoo, kuka voi käyttää aluetta. Oletusarvo on yrityksesi jäsenet. Toinen asetus avaa sen ulkopuolisille, mutta vain chatissa, jossa on myös joku yrityksesi jäsen: täsmälleen se tilanne, jota varten se on tarkoitettu, asiakas tekee tilauksen sinulta. Kun yrityksesi poistuu chatista, käyttöoikeus päättyy itsestään.

Oman tuotekatalogisi tuotteet

Kun olet lataanut tuotekatalogisi, rakentaja tarjoaa tuotevalitsin-lohkon. Säädettävää ei ole: lista on katalogisi. Tilaaja etsii sitä, näkee kuvan, nimen ja artikkelinumeron, ja taustajärjestelmäsi saa artikkelinumeron. Skava hylkää numeron, joka ei ole katalogissasi. Määräkentäksi aseta sen viereen tavallinen numerokenttä.

Määritä kortti itse

Taustajärjestelmäsi päättää, mitä kortissa lukee. Skava tarkistaa vain muodon, koon ja turvallisuuden, ei merkitystä: se ei tiedä tilausvaiheista eikä kenttien nimistä. Tee näin vastauksena card-objektilla:

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

• v:n on oltava kokonaisluku 1. Ilman sitä vastausta ei pidetä korttina, ja elementissä määritetty vastauksen kartoitus astuu voimaan.
• state on vain väri ja kuvake: ok, pending, warn tai error. Kaikki merkityksellinen sisältö kuuluu vapaana tekstinä kohtaan status_text.
• fields on lista, jossa on enintään 20 otsikon ja arvon paria. Liian pitkät arvot lyhennetään sen sijaan, että niitä hylättäisiin, jotta tilaus ei epäonnistu yksityiskohdan vuoksi.

Käyttäjän syötteet kuuluvat palvelimelle: niitä ei muuteta riippumatta siitä, mitä taustajärjestelmäsi lähettää. Ne ovat keskustelun arkistona siitä, mitä todella lähetettiin.

Tilan raportointi myöhemmin

Kun elementti suoritetaan, Skava lähettää kaksi lisäarvoa: callback_url ja callback_token. Raportoi uusi tila sinne myöhemmin, ja uusi kortti ilmestyy keskusteluun myös puhelimeen, vaikka joku katselee sitä. Edellinen kortti säilyy, jotta tilan vaihtuminen on jälkikäteen luettavissa. Lähetä sama card-objekti kuin yllä POST-pyynnöllä, jonka otsake on Authorization: Bearer <callback_token>. Kortin viereen lisätään kolme valinnaisen arvoa:

• seq: oma laskurisi. Pienempi tai yhtä suuri arvo hylätään, joten kaksi raporttia eivät voi ohittaa toisiaan.
• final: päättää vuorovaikutuksen. Token muuttuu voimattomaksi ja kortti on lopullinen.
• notify: aseta arvoksi false, jotta kortti julkaistaan hiljaa ilman lukemattomien määrää ja ilmoitusta. Tämä sopii välivaiheisiin, jotka eivät herätä ketään. Ilman tätä kortti on täysin normaali viesti.

Vuorovaikutus voi julkaista enintään 50 korttia. Sama raportti kahdesti ei tuota toista korttia.

Skava vastaa koodilla 200 ja hints-listalla, jos jotain lyhennettiin tai pudotettiin, ja koodilla 422, jos kortti oli käyttämätön. Vuorovaikutus hyväksyy raportteja 90 päivän ajan.

Kortit julkaistaan Skavan järjestelmän lähettäjän toimesta, ei henkilön, joka suoritti elementin, eikä oman yrityksesi tilin toimesta. Kortin otsikossa kerrotaan, kenen järjestelmä on kirjoittanut viestin.

Koko kopioitava esimerkki sijaitsee arkistossa hakemistossa example_order_server/ ja se toimii osoitteessa api.skava.io.

Liittyvät

Haluatko sen sijaan luoda täytettävän asiakirjapohjan? Katso Custom Elements: Asiakirjat.

Usein kysytyt kysymykset