Skava Skava / Wiki

Yhteys mukautettuihin elementteihin kehittäjille

Tämä sivu on tarkoitettu kehittäjille, jotka yhdistävät yrityksen taustajärjestelmän Skavaan. API-elementin luominen ja julkaiseminen käsitellään sivulla Mukautetut elementit: API-liittymät. Tässä käsittelemme kaiken, mitä on tehtävä linjan toisessa päässä.

Idea yhdellä lauseella: Skava ei tunne alalasi. Se tuntee täsmälleen yhden muodon, kortin. Sinä päätät, mitä se sisältää, ja me tarkistamme vain muodon, koon ja turvallisuuden. Materiaaltilaus on yksi esimerkki; seuraava yritys kerää käyttäjäpalautetta, ja sitä seuraava tallentaa työmaakuvalan omiin kirjoihinsa.

Prosessi lyhyesti

  1. Yrityksen ylläpitäjä luo API-elementin Skavassa: lomake sekä taustajärjestelmäsi osoite, metodi ja token.
  2. Joku chatissa täyttää lomakkeen ja lähettää sen.
  3. Skava kutsuu backendiäsi ja lähettää täytetyt arvot JSON-muodossa.
  4. Vastauksestasi tulee kortti chatissa.
  5. Valinnaisesti voit raportoida uusia tiloja myöhemmin callback:in kautta. Jokaisesta raportista tulee uusi kortti, ja edellinen säilyy.

Backendiäsi koskevat vaatimukset

  • HTTPS. Vain https://, ei http, ei tunnuksia osoitteessa, enintään 2000 merkkiä.
  • Julkisesti saavutettava. Isännän on vastattava ainoastaan julkisiin IP-osoitteisiin. Localhost, yksityiset verkot, linkkilokaalit ja pilvipalvelimet hylätään, ja tämä tarkistetaan jokaisella kutsulla.
  • Kiinteä osoite. Skava ratkaisee isännän kerran ja kiinnittää yhteyden kyseiseen IP-osoitteeseen. DNS-muutos kutsun aikana ei vaikuta yhteyteen.
  • Ei uudelleenohjauksia. 301-vastaus "oikeaan" osoitteeseen lasketaan virheeksi. Syötä lopullinen osoite heti.
  • Vastausaika. Aikakatkaisu on määritettävissä elementti kohtaan ja sen yläraja on 30 sekuntia. Jos tarvitset pidemmän ajan, vastaa heti ja ilmoita tulos myöhemmin takaisinkutsun kautta.
  • Vastauksen koko. Skava lukee enintään 256 KiB.
  • Content-Type. Runko tulkitaan vain, jos se on application/json.

Pyyntö, joka saapuu sinulle

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

Tunnistautuminen tapahtuu yhden otsikon avulla, jonka nimi ja arvon etuliite määritetään elementissä. Yleensä kyseessä on Authorization otsikko, jossa etuliite on Bearer . Avain tallennetaan salattuna puolellamme. Otsikoita host, content-length, content-type, cookie ja accept-encoding ei voi asettaa.

Runko on litteä objekti. Avaimet valitsee elementin rakentaja; sisennys näkyy vain, jos he ovat lisänneet taulukon tai tuotteen valitsimen:

{"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 sillä kielellä; emme käännä tekstejäsi.
  • callback_url ja callback_token: takaisinkutsu tälle yhteen vuorovaikutukselle, ks. alla. Ne ovat läsnä vain, jos kutsu tulee chatista.

Yhteystietokentät, kuten nimi, yritys, projekti tai alakeskustelu, täytetään palvelimella itse. Ne johdetaan kanavasta, jossa elementti ajettiin. Muokattu asiakas ei voi väittää siellä eri projektinimeä.

Vastaus: korttimuoto

Vastaa koodilla 2xx ja card-objektilla. Tämä on se, joka muodostaa kortin chatissa:

{"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 lasketa kortiksi ja elementissä määritetty vastauksen kartoitus sovelletaan.
  • title: kortin otsikko.
  • state: vain väri ja ikoni, yksi arvoista ok, pending, warn, error. Tuntematon arvo palauttaa arvon ok ja saat vinkin.
  • status_text: vapaa teksti, jota emme tulkita. Se näkyy kortin yläreunassa sekä chat-listassa ja push-ilmoituksessa.
  • fields: lista label- ja value-kentistä. Enintään 20 kohdetta, label 80 merkkiä, value 200, title ja status_text 120 kumpikin. Liian pitkät arvot lyhennetään, eikä niitä hylätä: tilauksen ei tulisi epäonnistua yksityiskohdan vuoksi.
  • icon: ks. alla.

Mitä Skava tekee teksteillesi ennen niiden saapumista chatiin: rivinvaihdot ja ohjausmerkit poistetaan (oikealta vasemmalle kirjoitettava merkki voisi muuten kääntää summan näkymisen), takalakit korvataan ja kaikki [SKAVA:-alkuiset osat neutraloidaan. Viimeinen estää kortin arvon tulkinnan toiseksi chat-alkioksi, esimerkiksi maksupyynnöksi.

Linkkejä, HTML:ää ja kuvia ei voi asettaa kenttiin. Chat on luotettava ympäristö, ja ulkoisen backendin klikattava osoite olisi kutsu rakentamaan uudestaan kirjautumissivu.

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

Kuvakkeet

Kortti saa otsikkoon oman merkkinsä icon-ominaisuudella. Kaksi tapaa:

Nimi mukana toimitetusta 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 ja niiden numeeriset ominaisuudet) ja rakentaa oman kuvansa. Skriptit, tyylit, ulkoiset viitteet, foreignObject ja tapahtumaominaisuudet 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ää itseään ohjainelementtinä. Työskentele 24 x 24 ruudukolla.

Ilman icon-kenttää oletusmerkki säilyy.

Kutsu: myöhempien tilojen raportointi

Kutsu sisältää callback_url- ja callback_token-kentät. Käytä niitä raportoidaksesi uudet tilat myöhemmin:

POST <callback_url> otsakkeilla Authorization: Bearer <callback_token> ja Content-Type: application/json, rungon enimmäiskoko 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 valinnaisaa arvoa:

  • seq: oma laskuri. Raportti, jonka arvo on pienempi tai yhtä suuri, hylätään, jotta kaksi raporttia ei voi ohittaa toisiaan. Ilman seq-kenttää viimeksi saapunut voittaa.
  • final: sulkee vuorovaikutuksen. Token muuttuu voimattomaksi ja uusia kortteja ei enää näy. Sallitaan myös ensimmäisessä vastauksessa, jos prosessissa ei ole jatkotoimia.
  • notify: aseta arvoksi false, jos kortin halutaan julkaista 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.

Jokainen raportti muuttuu omaksi kortikseen chatissa, ja edellinen säilyy. Näin näkyy, mikä tila on raportoitu. Tästä seuraa suositus: lähetä vain muuttuneet tiedot. Kortti, joka toistaa tilausnumeron, tuotteet ja yhteensä neljättä kertaa, on vain kohina lukijalle.

Kaksi rajaa: sama raportti kahdesti ei tuota 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: niistä näkee, mitä on lyhennetty tai jätetty pois.
  • 401: väärä token tai vuorovaikutus-tunniste. Älä yritä uudelleen.
  • 410: vuorovaikutus on suljettu tai vanhentunut. Älä yritä uudelleen.
  • 422: kortti ei ole käytettävissä, ja hints sisältää syyn. Korjaa se ensin.
  • 400 virheellinen JSON, 413 liian suuri, 429 liian monta pyyntöä (toista viiveellä), 500 meidän virhe, toista myöhemmin.

Esimerkki 1: tilaus, jossa on tilahistoria

Vaihe 1, pyyntö taustajärjestelmääsi:

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 vastaus:

{"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 paketti-ikoni, tila ja käyttäjän syötteet.

Vaihe 3, valinnan yhteydessä:

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

Toinen kortti ilman kenttiä: vain tila muuttui.

Vaihe 4, lähetysvaiheessa:

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, siksi ei ole notify: false.

Vaihe 5, toimitusvaiheessa:

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

Kun käytetään final, vuorovaikutus suljetaan ja token ei enää toimi.

Esimerkki 2: toiminto ilman jatkoaskelia

Kaikissa prosesseissa ei ole historiaa. Jos elementissä on vain yksi kenttä, joka siirtää jotain järjestelmääsi, riittää 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 avoimena 90 päivän ajan validilla tokenilla, vaikka et enää koskaan raportoi mitään.

Tuotteen valinta kataloogista

Kun yritys on ladannut artikkelikataloginsa, elementti voi sisältää tuotteen valitsimen. Käyttäjä kokoaa siitä ostoskorin, ja saat sen listana avaimen alla, jonka elementin rakentaja 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ä. Ennen lähettämistä Skava tarkistaa, että jokainen numero todella löytyy kyseisen yrityksen katalogista, enintään 50 kohdetta. Kortissa tuotteet näkyvät listana, jossa on tuotekuva, nimi ja määrä.

Testaus

  • Ping elementin muokkajessa lähettää paljaan HEAD-pyynnön ilman tokenia ja ilman dataa. Vastaa mistä tahansa; mikä tahansa HTTP-vastaus lasketaan tavoitettavaksi.
  • Testipyyntö suorittaa todellisen kutsun esimerkkiarvoilla, vaikka elementti olisi vielä luonnos, ja näyttää pyynnön, vastauksen sekä kortin validointiviestit.
  • Versio vierehkässä vieressä: liitä vastaus-JSON, tarkista ja näet valmiin kortin sekä vihjeet. Tarkistus tapahtuu palvelimella tuotantokoodin kanssa samalla tavalla.
  • Esimerkkipalvelin: täydellinen esimerkkitoimittaja toimii osoitteessa api.skava.io ja käyttää kaikkia yllä kuvattuja ominaisuuksia. Lähdekoodi löytyy varastosta hakemistosta example_order_server/, noin 600 riviä pelkkää standardikirjastoa, tarkoitettu kopioitavaksi.

Mitä muuta sinun kannattaa tietää

  • Kortti on täysin tavallinen viesti. Se näkyy hakuissa, sitä voi lainata ja se säilyy historiassa.
  • Sen lähettää järjestelmän lähettäjä, ei yrityksesi tili. Se sijoittuu silti sen puolelle, joka suoritti elementin, ja otsikossa kerrotaan, kenen järjestelmä kirjoittaa.
  • Käyttöoikeuden määrää elementissä: vain yrityksen jäsenet tai myös ulkopuoliset, jotka jakavat sen kanssa keskustelun. Kun yrityksesi poistuu keskustelusta, oikeus päättyy automaattisesti.
  • API-elementti, jonka token on vanhentunut, on lepotilassa: nykyiset sovellukset piilottavat sen valikosta, ja mahdollinen kutsu hylätään palvelimella. Ylläpitäjä tallentaa sille uuden tokenin, mikä toimii myös julkaistulla rajapinnalla.

Liittyvät

Luominen ja julkaisu: Custom Elements: API-rajapinnat. Täytettävät asiakirjat rajapintojen sijaan: Custom Elements: Asiakirjat.