Tämä sivu on tarkoitettu kehittäjille, jotka yhdistävät yrityksen takapään Skavaan. API-elementin luominen ja julkaiseminen käsitellään sivulla Custom Elements: API-liittymät; tässä käymme läpi kaiken, mitä on tehtävä toisessa päässä.

Ajatus yhdessä lauseessa: Skava ei tunne alaa. Se tuntee täsmälleen yhden muodon, kortin. Sinä päätät, mitä se sanoo; me tarkistamme vain muodon, koon ja turvallisuuden. Materiaalintilaus on yksi esimerkki; seuraava yritys kerää käyttäjäpalautetta, ja sitä seuraava tallentaa kohteen valokuvan omiin tietoihinsa.

Prosessi lyhyesti

1. Yrityksen ylläpitäjä luo API-elementin Skavaan: lomakkeen sekä takapääsi osoitteen, menetelmän ja tokenin.
2. Joku täyttää lomakkeen keskustelussa ja lähettää sen.
3. Skava kutsuu palvelintasi ja lähettää täytetyt arvot JSON-muodossa.
4. Vastauksestasi tulee kortti keskustelussa.
5. Valinnaisesti voit raportoida uudet tilat myöhemmin palautekutsun kautta. Jokainen raportti luo uuden kortin; edellinen kortti säilyy.

Vaatimukset palvelimellesi

• HTTPS. Vain https://, ei http, ei tunnistetietoja osoitteessa, enintään 2000 merkkiä.
• Julkinen saavutettavuus. Isäntänimen on osoitettava ainoastaan julkisiin IP-osoitteisiin. Paikallismuistia, yksityisiä verkkoja, linkki-osoitteita ja pilvipalveluiden metatietoja ei hyväksytä, ja tämä tarkistetaan jokaisella kutsulla.
• Kiinteä osoite. Skava ratkaisee isäntänimen kerran ja sitoo yhteyden kyseiseen IP-osoitteeseen. DNS-muutos kutsun aikana ei vaikuta mitenkään.
• Ei uudelleenohjauksia. 301-virhekoodi "oikeaan" osoitteeseen lasketaan epäonnistumiseksi. Syötä lopullinen osoite heti.
• Vastausaika. Aikakatkaisu on säädettävissä elementtiä kohden ja sen yläraja on 30 sekuntia. Jos tarvitset pidemmän ajan, vastaa välittömästi ja raportoi tulos myöhemmin takaisinkutsun kautta.
• Vastauksen koko. Skava lukee enintään 256 KiB.
• Content-Type. Varsinainen sisältö tulkitaan vain application/json-tyyppisenä.

Sinun saamasi pyyntö

Menetelmä on GET, POST, PUT tai PATCH alkiosta riippuen. POST, PUT ja PATCH -pyynnöissä arvot saapuvat JSON-muotoisena ruumiina, GET-pyynnöissä kyselyparametreina.

Todentaminen on yksi otsikko, jonka nimi ja arvon etuliite on määritetty alkiossa, yleensä Authorization etuliitteellä Bearer . Token säilytetään salattuna meidän puolellamme. Otsikoita host, content-length, content-type, cookie ja accept-encoding ei voi asettaa.

Ruumis on tasainen olio. Avaimet valitsee alkion rakentaja; sisäkkäisyys ilmenee vain siellä, missä on lisätty taulukko tai tuotteen valitsin:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Kolme avainta tulee aina meiltä, joten älä käytä niitä itse:

• locale: käyttäjän kielikoodi. Vastaa tällä kielellä; emme käännä tekstejäsi.
• callback_url ja callback_token: takaisinkutsu tälle yhdelle vuorovaikutukselle, ks. alla. Ne ovat läsnä vain, kun kutsu tulee keskustelusta.

Kontekstikentät kuten name, company, project tai subchat täytetään palvelimen toimesta kanavasta, jossa elementti suoritettiin. Väärennetty asiakasohjelma ei voi väittää siellä eri hankkeen nimeä.

Vastaus: korttimuoto

Vastaa koodilla 2xx ja card-objektilla. Tämä on täsmälleen se kortti, joka näkyy keskustelussa:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

• v (pakollinen): kokonaisluku 1. Tekstinä ("1") se hylätään. Ilman tätä vastausta ei pidetä korttina, vaan sovelletaan elementissä määriteltyä vastauksen kartoitusta.
• title: kortin otsikko.
• state: vain väri ja kuvakkeen sävy, yksi vaihtoehdoista ok, pending, warn, error. Tuntematon arvo palauttaa oletusarvon ok ja saat vihjeen.
• status_text: vapaamuotoinen teksti, jota emme tulkita. Se sijaitsee kortin yläosassa ja näkyy myös keskusteluvalikossa sekä push-ilmoituksessa.
• fields: lista, jossa on label ja value. Enintään 20 kohtaa, label 80 merkkiä, value 200, title ja status_text kumpikin 120. Liian pitkät arvot lyhennetään, ei hylätä: tilauksen ei tulisi epäonnistua yksityiskohdan vuoksi.
• icon: ks. alla.

Mitä Skava tekee teksteillesi ennen kuin ne saapuvat keskusteluun: rivinvaihdot ja ohjausmerkit poistetaan (oikealta vasemmalle suuntautuva merkki voisi muuten kääntää summan näkymän), takaviivat korvataan ja kaikki, mikä alkaa merkeillä [SKAVA:, neutraloidaan. Viimeinen estää kortin arvon tulkinnan toisen keskustelu-elementin, kuten maksupyyntö, muodossa.

Linkkejä kentissä, HTML:ssä ja kuvissa ei voi asettaa. Keskustelu on luotettava ympäristö, ja ulkoisen takapään klikattava osoite olisi kutsu uudelleenrakentaa kirjautumissivu.

Käyttäjän syötteet kuuluvat palvelimelle: ne näkyvät ensimmäisellä kortilla, eikä niitä voi ylikirjoittaa. Keskustelussa ne ovat todiste siitä, mitä todella lähetettiin.

Kuvakkeet

icon-elementillä kortille saa oman merkinnän otsikkoon. Kaksi tapaa:

Nimi mukana tulevasta joukosta: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Tai oma SVG merkkijonona. Skava ottaa siitä vain geometrian (path, circle, ellipse, rect, line, polyline, polygon niiden numeeristen attribuuttien kanssa) ja luo oman kuvan. Skriptit, tyylit, ulkoiset viittaukset, foreignObject ja tapahtuma-attribuutit hylätään; doctype tai entiteetti johtaa hylkäämiseen; tiedoston koko saa olla enintään 8 KiB ja siinä saa olla enintään 16 muotoa. Väri, viivan paksuus ja koko määritetään Skavassa, joten kuvake ei voi esittäytyä ohjausalkioksi. Työskentele 24 x 24 ruudukolla.

Ilman icon-elementtiä oletusmerkintä säilyy.

Takaisinkutsu: myöhempien tilojen raportointi

Kutsu sisältää callback_url- ja callback_token-arvot. Käytä niitä uusien tilojen raportointiin myöhemmin:

POST <callback_url> -pyyntö, jossa on Authorization: Bearer <callback_token> ja Content-Type: application/json, ja jonka kehon koko on enintään 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Kortin lisäksi on kolme valinnaisen arvoa:

• seq: oma laskurisi. Pienemmän tai saman arvon omaava raportti hylätään, jotta kaksi raporttia eivät voi ohittaa toisiaan. Ilman seq-arvoa viimeisenä saapunut voittaa.
• final: lopettaa vuorovaikutuksen. Token muuttuu voimattomaksi, eikä enää uusia kortteja näytetä. Sallittu myös first-vastauksessa, jos vuorovaikutuksessa ei ole jatkovaiheita.
• notify: aseta arvoksi false, jotta kortti julkaistaan hiljaa ilman lukemattomien viestien määrää ja ilmoituksia. Sopii välivaiheisiin, jotka eivät vaadi herättämään ketään. Ilman tätä kortti on täysin normaali viesti.

Jokainen raportti luo oman korttinsa keskusteluun, ja edellinen säilyy. Näin näkee, mikä tila on raportoitu. Tästä seuraa suositus: lähetä vain muuttuneet tiedot. Kortti, joka toistaa tilausnumeron, tuotteet ja yhteissumman neljättä kertaa, on vain kohina lukijalle.

Kaksi rajaa: sama raportti kahdesti ei luo toista korttia, ja vuorovaikutus voi julkaista enintään 50 korttia. Vuorovaikutus hyväksyy raportteja 90 päivän ajan.

Vastaukset, joihin sinun tulee reagoida

• 200 ja {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Lue vihjeet: niissä kerrotaan, mitä on lyhennetty tai pudotettu.
• 401: väärä token tai vuorovaikutus-id. Älä yritä uudelleen.
• 410: vuorovaikutus suljettu tai vanhentunut. Älä yritä uudelleen.
• 422: kortti ei käytettävissä, syy on hints. Korjaa se ensin.
• 400 rikki JSON, 413 liian suuri, 429 liian monta pyyntöä (yritä uudelleen viiveellä), 500 meidän virhe, yritä myöhemmin uudelleen.

Esimerkki 1: tilaus, jossa on tilahistoria

Vaihe 1, pyyntö palvelimellesi:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Vaihe 2, välitön vastauksesi:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Chatissa näkyy nyt kortti, jossa on pakettikuvake, tila ja käyttäjän syötteet.

Vaihe 3, myöhemmin poiminnan aikana:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Tyyne toinen kortti ilman kenttiä: vain tila muuttui.

Vaihe 4, toimituksen yhteydessä:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Tämä kortti saattaa herättää jonkun, joten ei notify: false.

Vaihe 5, vastaanoton yhteydessä:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

final-parametrin avulla vuorovaikutus suljetaan ja token ei enää toimi.

Esimerkki 2: toiminto ilman seurauksia

Kaikilla virtauksilla ei ole historiaa. Jos alkuosassa on vain yksi kenttä, joka siirtää jotain järjestelmääsi, tarvitaan vain yksi vastaus:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true on tässä tärkeä: muuten vuorovaikutus pysyisi avoinna 90 päivän ajan kelvollisella tokenilla, vaikka et koskaan raportoi enää mitään.

Tuotteen valitsija tuotekirjastosta

Kun yritys on lataanut tuotekirjastonsa, alkuosa voi sisältää tuotteen valitsija-lohkon. Käyttäjä koostaa siitä ostoskorin, ja saat sen listana avaimen alla, jonka alkuosan luonut on valinnut:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Koska avain on vapaa, etsi ensimmäinen lista, jolla on tämä muoto, eikä kiinteää nimeä. Lähetystä ennen Skava varmistaa, että jokainen numero todella löytyy kyseisen yrityksen luettelosta, enintään 50 kohdetta. Kortissa kohteet näkyvät listana, jossa on tuotekuva, nimi ja määrä.

Testaus

• Ping alkuarvojen muokkaimessa lähettää pelkän HEAD-pyynnön ilman tokenia ja dataa. Vastaa millä tahansa; mikä tahansa HTTP-vastaus lasketaan saavutettavaksi.
• Test request suorittaa todellisen kutsun esimerkkiarvoilla, vaikka alkuarvo on vielä luonnoksena, ja näyttää pyynnön, vastauksen sekä kortin validointiviestit.
• Preview viereisessä välilehdessä: liitä vastaus-JSON, tarkista ja näet valmiin kortin sekä vihjeet. Se tarkistetaan palvelimella samalla koodilla kuin tuotannossa.
• Esimerkkipalvelin: täydellinen esimerkkitoimittaja toimii osoitteessa api.skava.io ja käyttää kaikkia edellä kuvattuja ominaisuuksia. Sen lähdekoodi sijaitsee arkistossa hakemistossa example_order_server/, noin 600 riviä puhdasta standardikirjastoa, joka on tarkoitettu kopioitavaksi.

Mitä muuta sinun tulisi tietää

• Kortti on täysin normaali viesti. Se näkyy hakuissa, sitä voi lainata ja se säilyy historiassa.
• Sen lähettää järjestelmä, ei yrityksesi tili. Se näkyy kuitenkin sen henkilön puolella, joka suoritti elementin, ja otsikossa mainitaan, kenen järjestelmä kirjoittaa.
• Kuka voi suorittaa sen, määritetään elementissä: vain yrityksen jäsenet vai myös ulkopuoliset, jotka jakavat keskustelun. Kun yrityksesi poistuu keskustelusta, oikeus päättyy itsestään.
• API-elementti, jonka token on vanhentunut, on inaktiivinen eikä näy valikossa, ennen kuin ylläpitäjä tallentaa uuden tokenin.

Liittyvät aiheet

Luominen ja julkaiseminen: Mukautetut elementit: API-liittymät. Täytettävät asiakirjat liittymien sijaan: Mukautetut elementit: Asiakirjat.