See leht on mõeldud arendajatele, kes ühendavad ettevõtte tagaosa Skavaga. Kuidas API elementi luua ja avaldada, on kirjeldatud lehel Kohandatud elemendid: API liidesed; siin käsitleme kõike, mis peab toimuma teisel liini otsas.

Mõte ühes lauses: Skava ei tea teie valdkonda. See teab täpselt ühte formaati, kaarti. Te otsustate, mida see ütleb, me kontrollime ainult kuju, suurust ja turvalisust. Materjalide tellimine on üks näide; järgmine ettevõte kogub kasutajate tagasisidet, järgmine salvestab ehitusobjekti foto oma arhiivi.

Voolu ülevaade

1. Ettevõtte administraator loob Skavas API elemendi: vormi koos teie tagaosaga aadressi, meetodi ja tokeniga.
2. Keegi vestluses täidab vormi ja saadab selle.
3. Skava kutsub teie tagasüsteemi ja saadab täidetud väärtused JSON-vormingus.
4. Teie vastus muutub vestluses kardiks.
5. Vajadusel saate hiljem teatada uuest olekust läbi tagasisidefunktsiooni. Iga teade muutub uueks kardiks; eelmine jääb alles.

Nõuded teie tagasüsteemile

• HTTPS. Ainult https://, mitte http, aadressis ei tohi olla usaldusandmeid, maksimaalselt 2000 märki.
• Üldselt ligipääsetav. Host peab lahenduma ainult avalike IP-aadressidega. Kohalik host, privaatvõrgud, link-lokaal ja pilvemetaandata on keelatud ning seda kontrollitakse igal kõnel.
• Kinnitatud aadress. Skava lahendab hosti ühe korra ja fikseerib ühenduse sellele IP-le. DNS-i muutmine kõne ajal ei mõjuta midagi.
• Punamisi ümbersuunamisi. 301 ümbersuunamine "õigele" aadressile loetakse ebaõnnestumiseks. Sisestage lõplik aadress kohe.
• Vastuse aeg. Ajapiirang on iga elemendi jaoks seadistatav ja rangelt piiratud 30 sekundiga. Kui vajate pikemat aega, vastake kohe ja teatage tulemusest hiljem tagasiside kaudu.
• Vastuse suurus. Skava loeb maksimaalselt 256 KiB.
• Content-Type. Sisu tõlgendatakse ainult application/json väärtusega.

Teile saabuva taotluse

Meetod on GET, POST, PUT või PATCH, sõltuvalt elemendist. POST, PUT ja PATCH puhul saadetakse väärtused JSON kehas, GET puhul aga päringuparameetritena.

Autentimine toimub ühe päise abil, mille nimi ja väärtuse eesliide on elemendis konfigureeritud, tavaliselt Authorization eesliitega Bearer . Token on meie poolt krüpteerituna salvestatud. Päiseid host, content-length, content-type, cookie ja accept-encoding ei saa määrata.

Keha on tasane objekt. Võtmed on valitud elemendi looja poolt; sisestumine ilmneb ainult seal, kus on lisatud tabel või tootevalija:

{"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 võtit saadame alati meie poolt, seega ärge kasutage neid ise:

• locale: kasutaja keelekood. Vastake selles keeles; me ei tõlgi teie tekste.
• callback_url ja callback_token: tagasiside üksikule vastastikusele tegevusele, vt allpool. Need on olemas ainult siis, kui kõne tuleb vestlusest.

Kontekstiväljad, nagu nimi, ettevõte, projekt või alamvestlus, täidab server ise, tuletades need kanalist, milles elementi käivitati. Muundatud klient ei saa seal väita teistsugust projekti nime.

Vastus: kaardi formaat

Vasta koodiga 2xx ja card objektiga. Just see muutub vestluses kaardiks:

{"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 (kohustuslik): täisarv 1. Tekstina ("1") seda ei aktsepteerita. Ilma selleta ei loeta vastust kaardiks ja kehtib elemendis konfigureeritud vastuse kaardistamine.
• title: kaardi pealkiri.
• state: ainult värv ja ikooni toon, üks järgmistest: ok, pending, warn, error. Tundmatu väärtus lükkab tagasi ok ja saadate vihje.
• status_text: vaba tekst, mida me ei tõlgenda. See asub kaardi ülaosas ja on see, mis ilmub vestluste loendis ja teates.
• väljad: loetelu label ja value paaridest. Kuni 20 kirjet, label kuni 80 tähemärki, value kuni 200, title ja status_text mõlemad kuni 120. Liiga pikad väärtused lühendatakse, mitte tagasi lükatakse: tellimus ei tohi ebaõnnestuda üksikasja tõttu.
• ikoon: vt allpool.

Mida Skava teie tekstidega teeb enne vestlusesse jõudmist: reavahetused ja juhtkarakterid eemaldatakse (paremalt-vasakule suunav karakter võiks muidu summa kuvamist pöörata), tagatähed asendatakse ja kõik, mis algab [SKAVA:ga, neutraliseeritakse. Viimane takistab kaardi väärtuse lugemist kui mõnda muud vestluselementi, näiteks maksepalvet.

Väljadesse, HTML-i ja piltidesse ei saa lisada linke. Vestlus on usaldusväärne keskkond ja võõra tagaotsast pärit klõpsatav aadress oleks kutse üles ehitada sisselogimisleht.

Kasutaja sisselülitused kuuluvad serverile: need ilmuvad esimesel kaardil ja neid ei saa üle kirjutada. Vestluses on need tõend sellest, mis tegelikult esitati.

Ikoonid

icon lisab kaardi pealkirja oma märgi. Kaks võimalust:

Nimi kaasatud komplektist: 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.

Või oma SVG sõne kujul. Skava kasutab sellest ainult geomeetriat (path, circle, ellipse, rect, line, polyline, polygon koos nende arvuliste atribuutidega) ja loob oma pildi. Skriptid, stiilid, välised viited, foreignObject ja sündmusatribuudid eemaldatakse; dokumenditüüp või entiteet põhjustab tagasilükkamise; faili suurus ei tohi ületada 8 KiB ja see ei tohi sisaldada rohkem kui 16 kuju. Värv, joone paksus ja suurus määrab Skava, seega ei saa ikoon end nupuks maskeerida. Tööta 24 x 24 ruudustikuga.

Ilma icon jääb vaikimisi märk.

Tagasiside: hilisemate olekute teavitamine

Kõne sisaldab callback_url ja callback_token. Kasuta neid hilisemate olekute teavitamiseks:

POST <callback_url> päisega Authorization: Bearer <callback_token> ja Content-Type: application/json, keha maksimaalselt 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}

Kaardi kõrval on kolm väärtust, mis on valikulised:

• seq: oma loendur. Teatis väiksema või võrdse väärtusega jäetakse tähelepanuta, et kaks teatist ei saaks üksteist ületada. Ilma seq-ta võidab viimane saabunud teatis.
• final: lõpetab interaktsiooni. Token kehtetuks muutub ja uusi kaarte enam ei ilmne. Lubatud ka esimeses vastuses, kui järelküsimusi ei ole.
• notify: väärtuseks false seades postitatakse kaart vaikimisi, lugemata lugemise arvestust ja teavitust ei teki. Sobib vaheastmetele, mis ei tohiks kedagi ärkama panna. Ilma selleta on kaart täiesti tavaline sõnum.

Iga aruanne muutub oma kaardiks vestluses, eelmine jääb alles. Nii on näha, millist seisundit teatati. Sealt tuleneb soovitus: saatke ainult muutunud andmed. Kaart, mis kordab neljandat korda tellimuse numbrit, positsioone ja kogusummat, on lugejale lihtsalt müra.

Kaks piirangut: sama aruande saatmine kaks korda ei loo teist kaarti ja interaktsioon võib postitada maksimaalselt 50 kaarti. Interaktsioon aktsepteerib aruandeid 90 päeva jooksul.

Vastused, millele tuleb reageerida

• 200 koos {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []} vastusega. Lugege vihjeid: need ütlevad, mida on lühendatud või välja jäetud.
• 401: vale token või interaktsiooni ID. Ärge proovige uuesti.
• 410: interaktsioon on suletud või aegunud. Ärge proovige uuesti.
• 422: kaart on kasutamatu, põhjus on hints. Parandage see kõigepealt.
• 400 vigane JSON, 413 liiga suur, 429 liiga palju taotlusi (korrake proovi viivituseta), 500 meie viga, proovige hiljem uuesti.

Näide 1: tellimus, millel on staatuse ajalugu

Samm 1, taotlus teie tagasüsteemile:

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"}

Samm 2, teie kohene vastus:

{"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"}]}}

Vestluses kuvatakse nüüd kaart pakendi ikooniga, staatus ja kasutaja sisendid.

Samm 3, hiljem pakkimisel:

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

Vaikne teine kaart ilma väljadeta: muutus ainult staatus.

Samm 4, saatmisel:

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}

See kaart võib kedagi ärkama panna, seega ei ole notify: false.

Samm 5, kohaletoimetamisel:

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

Märgisega final on interaktsioon lõpetatud ja token enam ei tööta.

Näide 2: tegevus ilma järeltegevusteta

Igal voolul pole ajalugu. Element, millel on üks väli ja mis edastab midagi teie süsteemi, vajab vaid ühte vastust:

{"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 siin oluline: vastasel juhul jääb interaktsioon 90 päevaks avatuks kehtiva tokeniga, kuigi te ei raporteeri enam kunagi midagi.

Tootevalija kataloogist

Pärast seda, kui ettevõte on üles laadinud oma artiklite kataloogi, võib element sisaldada tootevalija ploki. Kasutaja koostab sellest ostukorvi ja te saate selle nimekirjana võtme all, mille on valinud elemendi looja:

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

Kuna võti on vaba, otsige esimest loendit, millel on see kuju, mitte kindlat nime. Saate enne Skava kontrollib, et iga number eksisteeriks tegelikult selle ettevõtte kataloogis, maksimaalselt 50 toodet. Kaardil ilmuvad tooted loendina koos tootepildiga, nimega ja kogusega.

Testimine

• Ping elementi redigeerides saadab palja HEAD päringu ilma tokenita ja andmeteta. Vastake millegagi; iga HTTP-vastus loeb saavutatavana.
• Testpärming tekitab reaalse kõne prooviväärtustega, isegi kui element on veel mustand, ja näitab päringut, vastust ning kaardi valideerija teateid.
• Eelvaade kõrvalasuvale vahelehele: kleepige oma vastuse JSON, kontrollige ja näete valmis kaarti koos vihjetega. See kontrollitakse serveris sama koodiga kui tootmises.
• Näidisserver: täielik näidis tarnija töötab aadressil api.skava.io ja kasutab kõiki ülal kirjeldatud funktsioone. Selle lähtekood asub hoidlas kataloogis example_order_server/, umbes 600 rea puhas standardraamatukogu, mis on mõeldud kopeerimiseks.

Mida veel teada peaks

• Kaart on täiesti tavaline vestlusviis. See ilmub otsingus, seda saab tsiteerida ja see jääb ajaloosse.
• Selle saadab süsteemi saatja, mitte teie ettevõtte konto. See ilmub ikkagi selle inimese poolel, kes elementi käivitas, ja pealkirjas on märgitud, kelle süsteem kirjutab.
• Kellel on õigus seda käivitada, määratakse elemendi juures: ainult ettevõtte liikmed või ka välised isikud, kellega vestlust jagatakse. Kui teie ettevõte vestlusest lahkub, lõpeb luba automaatselt.
• API-element, mille token on aegunud, on passiivne ja ei ilmu menüüsse, kuni administraator salvestab uue.

Seotud

Loomine ja avaldamine: Kohandatud elemendid: API-liidesed. Täidetavad dokumendid liideste asemel: Kohandatud elemendid: Dokumendid.