Mukautetut elementit: API

API-liittymä on lomake, jonka täytetyt arvot Skava lähettää JSON-muodossa sinun määrittämään osoitteeseen (oma backend). Näin voit yhdistää Skavan turvallisesti omiin järjestelmiisi.

Aseta API-liittymä

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

1. Luo kentät: Jokaiselle kentälle annetaan JSON-avain. Oikealla näet JSON-esikatselun reaaliajassa, joka lähetetään takasiimeesi täsmälleen tässä muodossa.
2. Osoite (URL): Takasiimesi https://-osoite. Sallitaan vain HTTPS- ja julkisesti saatavilla olevat osoitteet (ks. Turvallisuus alla).
3. Menetelmä: POST (oletus), PUT, PATCH tai GET. GET:n tapauksessa arvot liitetään kyselyparametreina eikä niitä lähetetä ruumiissa.
4. Tunnistautuminen: Määritä otsikon nimi (esim. Authorization) ja arvon etuliite (esim. Bearer ), ja tallenna token. Voit valinnaisesti asettaa voimassaoloajan.
5. Vastauskentät (valinnainen): Määritä polku, minkä arvot takasiimeen tulevasta vastauksesta haluat näyttää: esim. order.id tai items[0].sku.
6. Tarkista Ping ja Test Request, ja julkaise sitten Release.

Tallenna token turvallisesti

Token tallennetaan salaettuna ja sitä ei koskaan palauteta asiakkaille: sovellus näyttää vain onko token asetettu ja milloin se vanhenee. Lähetettäessä Skava liittää sen palvelimen puolella määritettyyn otsakkeeseen. Jos asetat vanhenemispäivämäärän, Skava hylkää kutsun vanhenemisen jälkeen ja pyytää sinua uudistamaan tokenin.

Testaus: Ping ja testikutsu

• Ping: kevyt saavutettavuustarkistus. Tarkistaa vain onko osoitteesi vastaava eikä lähetä tokenia tai lomakedataa. Näyttää saavutettavuuden, tilan ja vastausajan. Sopii ensimmäiseksi vaiheeksi.
• Testauspyyntö: todellinen kokeilu: lähettää esimerkkidataa tokenin kanssa osoitteesi ja näyttää koko vastauksen sekä poimitut vastauskentät.

Ylläpitäjänä voit suorittaa molemmat luonnostilassa varmistaaksesi integraation ennen julkaisua.

Luonnos ja julkaisu

Jokainen rajapinta alkaa luonnoksena ja sitä voi muokata vapaasti. Kun kaikki on valmista, julkaiset sen painikkeella Julkaise.

Turvallisuus

Miten tiimi käyttää julkaistua käyttöliittymää

Kun käyttöliittymä on julkaistu, kaikki yrityksen jäsenet voivat käynnistää sen suoraan chatista ilman muokkaustyökalua. Ei ole yhteistä syöttöä eikä välivälilehtiä: jokainen julkaistu elementti löytyy plusvalikosta omalla nimellään ja tarjoavan yrityksen logolla.

1. Chatissa napauta Plus alareunassa ja valitse haluamasi elementti, esimerkiksi Materiaaltilaus.
2. Täytä lomake ja napauta Lähetä.
3. Tulos näkyy korttina chatissa, ja kaikki chatin jäsenet voivat sen nähdä.

Anna tekoälyn rakentaa elementti

Yrityksen ylläpitäjänä et tarvitse itse käyttää muokkaajaa. Kerro Skava-apulaiselle chatissa esimerkiksi "tee minulle tilauslomake katalogiini, jossa on määrä ja toimitusosoite". Se luo siitä luonnoksen, voi muuttaa kenttiä myöhemmin yksitellen ja tuntee lataamasi artikkelikatalogin: tilauksissa se ehdottaa tuotteen valitsinta sen sijaan, että käyttäisi artikkelinumerolle tekstikenttää.

Se voi myös asettaa: päätepisteen ja metodin sekä yleisön ("vain yrityksen jäsenet" tai "myös ulkopuoliset samassa chatissa"). Yleisön kohdalla se kysyy ensin, eikä aseta sitä suoraan, koska se määrää, kuka voi ajaa jotain ulkopuolelta.

Mitä se ei koskaan koske: pääsytokenia. Se ei koskaan kysy sitä eikä hyväksy sitä, koska chat-viestit tallennetaan. Syötät sen itse muokkaajassa, muuten ei lähetetä yhtään kutsua. Se ei myöskään voi julkaisua: viimeinen vaihe jää sinulle, jotta mikään ei tule asiakkaille näkyväksi tarkistamatta.

Kuka voi ajaa sen

"Endpoint"-välilehti kertoo, kuka voi käyttää aluetta. Oletuksena se on yrityksesi jäsenet. Toinen asetus avaa sen ulkopuolisille, mutta vain chatissa, jossa on myös joku yrityksesi puolelta: juuri se tapaus, mihin se on tarkoitettu, asiakkaan tilaaminen sinulta. Kun yrityksesi poistuu chatista, oikeus päättyy itsestään.

Tuotteet omasta tuotekatalogistasi

Kun olet ladannut tuotekatalogisi, rakentaja tarjoaa tuotteen valitsin-lohkon. Valitsimessa ei ole ylläpidettäviä asetuksia: lista on suoraan katalogisi. Tilauksen tekevä hakee sieltä tuotteen, näkee kuvan, nimen ja artikkelinumeron, ja taustajärjestelmäsi saa artikkelinumeron. Skava hylkää numeron, joka ei ole katalogissasi. Määrälle lisää viereen tavallinen numerokenttä.

Määritä kortti itse

Taustajärjestelmäsi päättää, mitä kortti sisältää. Skava tarkistaa vain rakenteen, koon ja turvallisuuden, ei merkitystä: se ei tiedä tilausvaltioita eikä kenttien nimiä. Tee näin vastaaamalla 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 sovelletaan.
• state on vain väri ja ikoni: ok, pending, warn tai error. Kaikki merkityksellinen sisältö menee status_text-kenttään vapaana tekstinä.
• fields on lista nimikkeistä ja arvoista, enintään 20 kohdetta. Liian pitkät arvot lyhennetään eikä niitä hylätä, jotta tilaus ei epäonnistu pienestä yksityiskohdasta.

Käyttäjän syötteet kuuluvat palvelimelle: niitä ei muuteta, mitä tahansa taustajärjestelmäsi lähettääkään. Ne ovat chatissa tallennettu todiste siitä, mitä todellisuudessa lähetettiin.

Tilan raportointi myöhemmin

Kun elementti ajetaan, Skava lähettää kaksi lisäarvoa: callback_url ja callback_token. Raportoi uusi tila sinne myöhemmin, niin uusi kortti ilmestyy chatissa, myös puhelimessa, vaikka joku katselee. Edellinen kortti säilyy, jolloin näkyy, mikä tila on raportoitu. Lähetä sama card-objekti kuin yllä, POST-pyynnöllä otsikolla Authorization: Bearer <callback_token>. Kolme valinnista arvoa menee kortin viereen:

• seq: oma laskuri. Raportti, jonka arvo on pienempi tai yhtä suuri, hylätään, jolloin kaksi raporttia ei voi ohittaa toisiaan.
• final: sulkee vuorovaikutuksen. Token muuttuu voimattomaksi ja kortti on lopullinen.
• notify: aseta arvoksi false, jotta kortti julkaistaan hiljaisesti ilman lukemattomia laskureita ja ilmoituksia. Sopii välivaiheisiin, jotka eivät herätä ketään. Ilman tätä kortti on täysin tavallinen viesti.

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

Skava vastaa koodilla 200 ja listalla hints, jos jotain on lyhennetty tai pudotettu, ja koodilla 422, jos kortti oli käyttökelpoton. Vuorovaikutus hyväksyy raportteja 90 päivän ajan.

Kortit julkaistaan Skavan järjestelmän lähettäjänä, ei sen henkilön toimesta, joka ajoi elementin, eikä oman yrityksesi tilin kautta. Kortin otsikossa kerrotaan, kenen järjestelmä kirjoittaa.

Koko kopioitava esimerkki löytyy repositoriosta hakemistosta example_order_server/ ja se ajetaan osoitteessa api.skava.io.

Liittyvät artikkelit

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

Usein kysytyt kysymykset