Custom Elements: API

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

Opsæt en API-grænseflade

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

1. Opret felter: Hvert felt får en JSON-nøgle. Til højre ser du i realtid JSON-forhåndsvisningen, som sendes til din backend præcis på denne måde.
2. Adresse (URL): din backends https://-adresse. Kun HTTPS-adresser og offentligt tilgængelige adresser er tilladt (se Sikkerhed nedenfor).
3. Metode: POST (standard), PUT, PATCH eller GET. Med GET tilføjes værdierne som forespørgselsparametre i stedet for at blive sendt i kroppen.
4. Godkendelse: Angiv header-navnet (f.eks. Authorization) og værdiprefixet (f.eks. Bearer ), og gem derefter tokenet. Du kan valgfrit angive 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 derefter Release.

Gem token sikkert

Token gemmes krypteret og returneres aldrig til klienter: appen viser kun, om et token er indstillet, og hvornår det udløber. Ved afsendelse tilføjer Skava det server-side til den konfigurerede header. Hvis du indstiller en udløbsdato, afviser Skava opkaldet efter udløb og beder dig om at forny token.

Testning: Ping og Testopkald

• Ping : en let tilgængelighedstest. Den tjekker kun om din adresse svarer, og sender ikke token eller formulardata undervejs. Viser tilgængelighed, status og svaretid. Ideel som første skridt.
• Testanmodning : den rigtige prøvekjøring: sender prøvedata inklusive token til din adresse og viser dig det fulde svar samt de udtrukne svarfelter.

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

Udkast og frigivelse

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

Sikkerhed

Hvordan holdet bruger en udgivet grænseflade

Når en grænseflade er udgivet, kan alle medarbejdere i virksomheden udløse den direkte fra en chat: ingen editor nødvendig. Flowet er det samme som med dokumentskabeloner: vælg, udfyld, send.

1. I chatten trykker du på Plus nederst og vælger Eget element.
2. Vælg den ønskede skabelon eller grænseflade fra listen.
3. Udfyld formularen og Send.
4. Resultatet vises som et kort i chatten: synligt for alle i chatten.

Lad AI'en opbygge et element

Som virksomhedsadministrator behøver du ikke selv bruge editoren. Sig til Skava-assistenten i chatten, for eksempel "opret en bestillingsskema til min katalog med mængde og leveringsadresse". Den skaber et udkast ud fra det, kan ændre felter ét ad gangen senere, og den kender din uploadede artikelkatalog: for bestillinger foreslår den produktvælgeren frem for et tekstfelt til artikelnr.

Hvad den også kan indstille: endepunkt og metode samt modtagergruppe ("kun virksomhedsmedlemmer" eller "også udefrakommende i samme chat"). For modtagergruppen spørger den først i stedet for bare at indstille det, fordi det afgør, hvem der må køre noget fra udefra.

Hvad den eksplicit ikke rører ved: adgangstokenet. Den spørger aldrig efter et og accepterer aldrig et, fordi chatbeskeder gemmes. Du indtaster det selv i editoren, ellers sendes ingen anmodning. Og den kan ikke publicere: det sidste skridt forbliver hos dig, så intet bliver synligt for kunderne uden kontrol.

Hvem må køre det

Fanen "Endepunkt" angiver, hvem der må bruge et element. Standarden er medlemmerne af din virksomhed. Den anden indstilling åbner det op for udefrakommende, men kun i en chat, hvor der også er nogen fra din virksomhed: præcis det tilfælde, det er beregnet til, når kunden bestiller hos dig. Når din virksomhed forlader chatten, ophører tilladelsen automatisk.

Produkter fra din egen katalog

Når du har uploadet din artikelkatalog, tilbyder byggeblokken en produktvælger. Der er ingen indstillinger at vedligeholde: listen er din katalog. Personen, der bestiller, søger i den, ser billedet, navnet og artikelnummeret, og din backend modtager artikelnummeret. Skava afviser et nummer, der ikke er i din katalog. Til mængden placerer du et almindeligt talfelt ved siden af.

Definer kortet selv

Din backend bestemmer, hvad kortet siger. Skava tjekker kun form, størrelse og sikkerhed, aldrig betydning: det kender hverken bestillingsstatus eller feltnavne. For at gøre det svarer du 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 ind i status_text som frit tekst.
• fields er en liste over etiket og værdi, højst 20 indgange. Værdier, der er for lange, forkortes i stedet for at blive afvist, så en ordre aldrig fejler på grund af en detalje.

Brugerens indtastninger tilhører serveren: de forbliver uændrede, uanset hvad din 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 forbliver, så det er læseligt, hvilken status der blev rapporteret. Send det samme card-objekt som ovenfor via POST med headeren Authorization: Bearer <callback_token>. Tre valgfrie værdier følger efter kortet:

• seq: din egen tæller. En rapport med en mindre eller lig værdi kasseres, så to rapporter kan ikke overhale hinanden.
• final: afslutter interaktionen. Tokenet bliver ugyldigt, og kortet er endeligt.
• notify: sæt til false for at poste kortet stille, uden ulæst tæller og uden notifikation. Til mellemtrin, der ikke skal vække nogen. Uden det er kortet en helt almindelig besked.

En interaktion kan poste 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 udgives af Skavas systemsender, ikke af den person, der udløste 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 repositoryet under example_order_server/ og kører på api.skava.io.

Relateret

Vil du i stedet opbygge et udfyldeligt dokumentmal? Se Custom Elements: Dokumenter.

Ofte stillede spørgsmål