Brugerdefinerede elementer: API

Et API-grænseflade er et formular, hvis udfyldte værdier Skava sender som JSON til en adresse, du angiver (dit backend). På denne måde kan du forbinde Skava sikkert med dine egne systemer.

Opsæt en API-grænseflade

En grænseflade består af indfelter (de danner JSON), måladresse og godkendelse.

1. Opret felter: Hvert felt får en JSON-nøgle. Til højre ser du JSON-forhåndsvisningen i realtid, som sendes til din backend på præcis denne måde.
2. Adresse (URL): https://-adressen til din backend. Kun HTTPS og offentligt tilgængelige adresser er tilladt (se Sikkerhed nedenfor).
3. Metode: POST (standard), PUT, PATCH eller GET. Ved GET tilføjes værdierne som query-parametre i stedet for at sendes i bodyen.
4. Autentificering: Angiv header-navn (f.eks. Authorization) og værdipræfiks (f.eks. Bearer ), og gem derefter tokenet. Vælg evt. en udløbsdato.
5. Svarfelter (valgfrit): Definer via sti, hvilke værdier fra backend-svaret der skal vises: f.eks. order.id eller items[0].sku.
6. Tjek med Ping og Test Request, og udgiv derefter med Release.

Opbevar token sikkert

Tokenen opbevares krypteret og returneres aldrig til klienter: Appen viser kun om der er sat et token, og hvornår det udløber. Ved afsendelse tilføjer Skava det server-side til den konfigurerede header. Hvis du angiver en udløbsdato, afviser Skava opkaldet efter udløb og beder dig forny tokenen.

Test: Ping og testanmodning

• Ping: en let tilgængelighedstjek. Den tjekker kun om din adresse svarer og sender ikke token eller formulardata undervejs. Viser tilgængelighed, status og svartid. Ideelt som første skridt.
• Testanmodning: den rigtige prøve: sender eksempeldata inklusive token til din adresse og viser dig den fulde respons samt de udtrukne responsfelter.

Som administrator kan du køre begge dele, mens du stadig er i udkasttilstand, for at verificere integrationen før udgivelse.

Udkast og frigivelse

Hver interface starter som et udkast og kan redigeres frit. Når alt er klar, frigiver du den med Frigiv.

Sikkerhed

Sådan bruger teamet et udgivet interface

Når et interface er udgivet, kan alle virksomhedens medlemmer udløse det direkte fra en chat, uden at der er brug for en editor. Der er ingen fælles indgang og ingen mellemværende dialog: hvert udgivet element sidder i plus-menuen under sit eget navn, med logoet fra den virksomhed, der tilbyder det.

1. I chatten trykker du på Plus nederst og vælger det element, du ønsker, for eksempel Materialorder.
2. Udfyld formularen og tryk på Send.
3. Resultatet vises som et kort i chatten, som alle i chatten kan se.

Lad AI'en bygge et element

Som virksomhedsadministrator behøver du ikke selv at bruge editoren. Sig til Skava-assistenten i chatten, for eksempel "byg mig en bestillingsformular til min katalog med antal og leveringsadresse". Den opretter et udkast ud fra det, kan ændre felter ét ad gangen senere, og den kender dit uploadede varekatalog: til bestillinger foreslår den produktvælgeren i stedet for et tekstfelt til varenummer.

Den kan også sætte: endpoint og metode samt målgruppe ("kun virksomhedsmedlemmer" eller "også eksterne i samme chat"). For målgruppen spørger den først i stedet for blot at sætte den, fordi den afgør, hvem der må køre noget udefra.

Det, den bevidst ikke rører ved: adgangstokenen. Den spørger aldrig efter en og accepterer aldrig en, fordi chatbeskeder gemmes. Du indtaster den selv i editoren, ellers sendes der ingen kald. Og den kan ikke publicere: det sidste skridt er stadig dit, så intet bliver synligt for kunder uden kontrol.

Hvem der må køre det

Fanen "Endpoint" angiver, hvem der må bruge et element. Standarden er medlemmerne af din virksomhed. Den anden indstilling åbner det op for eksterne, men kun i en chat, hvor der også er en fra din virksomhed til stede: netop det tilfælde, det er ment til, nemlig kunden, der bestiller hos dig. Når din virksomhed forlader chatten, ophører tilladelsen af sig selv.

Produkter fra dit eget katalog

Når du har uploadet dit varekatalog, tilbyder byggeriet en produktvælger-blok. Der er ingen indstillinger, du skal vedligeholde: listen er dit katalog. Den bestillende søger i den, ser billedet, navnet og varenummeret, og dit backend modtager varenummeret. Skava afviser et nummer, der ikke findes i dit katalog. For mængden placerer du et almindeligt talfelt ved siden af.

Definér kortet selv

Dit backend bestemmer, hvad kortet siger. Skava tjekker kun form, størrelse og sikkerhed, aldrig betydning: Den kender hverken ordrestatus eller feltnavne. For at gøre det, svar med et card-objekt:

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

• v skal være heltallet 1. Uden det tæller svaret ikke som et kort, og det svarmapping, der er konfigureret i elementet, gælder.
• state er kun farve og ikon: ok, pending, warn eller error. Alt, der bærer betydning, skal stå i status_text som fritext.
• fields er en liste med etiketter og værdier, maksimalt 20 poster. Værdier, der er for lange, forkortes i stedet for at afvises, så en ordre aldrig fejler på grund af en detalje.

Brugerens input tilhører serveren: de forbliver urørte uanset hvad dit backend sender. De er optegnelsen i chatten over, hvad der faktisk blev indsendt.

Rapportering af status senere

Når elementet kører, sender Skava to ekstra værdier: callback_url og callback_token. Rapportér en ny status der senere, og et nyt kort vises i chatten, også på telefonen, mens nogen kigger. Det tidligere kort forbliver, så det er læsbart, hvilken status der blev rapporteret. Send samme card-objekt som ovenfor via POST med headeren Authorization: Bearer <callback_token>. Tre valgfrie værdier placeres ved siden af kortet:

• seq: dit eget tæller. En rapport med en lavere eller ligeværdig værdi forkastes, så to rapporter kan ikke overhale hinanden.
• final: afslutter interaktionen. Tokenet bliver ugyldigt, og kortet er endeligt.
• notify: sæt til false for at oprette kortet stille, uden udlæst-tæller og uden notifikation. Til mellemstadier, der ikke skal vække nogen. Uden dette er kortet en helt almindelig besked.

En interaktion kan oprette højst 50 kort. Den samme rapport to gange giver ikke et andet kort.

Skava svarer med 200 og en liste over hints, hvis noget blev forkortet eller droppet, og med 422, hvis kortet var ubrugeligt. En interaktion accepterer rapporter i 90 dage.

Kortene sendes af Skavas systemsender, ikke af den person, der kørte elementet, og ikke af en konto i dit eget firma. Hvilket system der skriver, fremgår af kortets titel.

Et komplet eksempel, du kan kopiere, findes i repositoryen under example_order_server/ og kører på api.skava.io.

Relateret

Vil du i stedet oprette en udfyldelig dokumentmal? Se Custom Elements: Dokumenter.

Ofte stillede spørgsmål