Egendefinerte elementer: API

Et API-grensesnitt er et skjema der Skava sender de utfylte verdiene som JSON til en adresse du angir (din backend). På denne måten kan du koble Skava sikkert til dine egne systemer.

Sett opp et API-grensesnitt

Et grensesnitt består av inndatafelt (de danner JSON), måladresse og autentisering.

1. Opprett felter: Hvert felt får en JSON-nøkkel. Til høyre ser du JSON-forhåndsvisningen i sanntid, som sendes til backenden din på akkurat denne måten.
2. Adresse (URL): https://-adressen til backenden din. Bare HTTPS og offentlig tilgjengelige adresser er tillatt (se Sikkerhet nedenfor).
3. Metode: POST (standard), PUT, PATCH eller GET. Med GET legges verdiene til som spørselsparametre i stedet for å sendes i kroppen.
4. Autentisering: Angi header-navn (f.eks. Authorization) og verdiprefiks (f.eks. Bearer ), og lagre deretter tokenet. Du kan eventuelt angi en utløpsdato.
5. Svarfelter (valgfritt): Definer via sti hvilke verdier fra backendens svar som skal vises: f.eks. order.id eller items[0].sku.
6. Sjekk med Ping og Test Request, deretter Release.

Lagre token trygt

Tokenet lagres kryptert og returneres aldri til klienter: appen viser bare om et token er satt og når det utløper. Ved sending legger Skava det til server-side i den konfigurerte headeren. Hvis du setter en utløpsdato, nekter Skava kall etter utløp og ber deg fornye tokenet.

Testing: Ping og testforespørsel

• Ping: en enkel tilgjengelighetstest. Den sjekker bare om adressen din svarer, og sender ikke token eller skjema data i prosessen. Viser tilgjengelighet, status og svartid. Ideell som første steg.
• Testforespørsel: den egentlige prøveløpet: sender eksempeldata inkludert token til adressen din og viser deg den komplette responsen samt de uttrekkede responsfeltene.

Som administrator kan du kjøre begge deler mens du fortsatt er i utkastmodus for å verifisere integrasjonen før lansering.

Utkast og utgivelse

Hver grensesnitt starter som et utkast og kan redigeres fritt. Når alt er klart, utgir du det med Utgiv.

Sikkerhet

Slik teamet bruker en utgitt grensesnitt

Når et grensesnitt er utgitt, kan alle selskapsmedlemmer starte det direkte fra en chat, uten behov for redigering. Det finnes ingen felles inngang og ingen mellomliggende dialog: hvert utgitt element ligger i plussmenyen under sitt eget navn, med logoen til selskapet som tilbyr det.

1. I chatten, trykk på Pluss nederst og trykk på elementet du ønsker, for eksempel Materialordre.
2. Fyll ut skjemaet og trykk på Send.
3. Resultatet vises som et kort i chatten, synlig for alle i chatten.

La AI bygge et element

Som selskapsadministrator trenger du ikke å bruke redaktøren selv. Si til Skava-assistenten i chatten, for eksempel «lag en bestillingsformular for katalogen min med antall og leveringsadresse». Den lager et utkast ut fra det, kan endre felt ett og ett senere, og kjenner den artikkellisten du har lastet opp: ved bestillinger foreslår den produktvelgeren i stedet for et tekstfelt for artikkelnummer.

Den kan også sette: endpoint og metode samt målgruppe («kun selskapsmedlemmer» eller «også eksterne i samme chat»). For målgruppen spør den først i stedet for å bare sette den, fordi den avgjør hvem som kan kjøre noe fra utsiden.

Det den uttrykkelig ikke rører: tilgangstokenen. Den ber aldri om en og aksepterer aldri en, fordi chatmeldinger lagres. Du fyller den inn selv i redaktøren, ellers sendes ingen kall. Og den kan ikke publisere: det siste steget ligger hos deg, så ingenting blir synlig for kunder uten at du har sjekket det.

Hvem som kan kjøre det

Fanen «Endpoint» sier hvem som kan bruke et element. Standardinnstillingen er medlemmene i selskapet ditt. Den andre innstillingen åpner det for eksterne, men bare i en chat der noen fra selskapet ditt også er til stede: akkurat tilfellet det er ment for, kunden som bestiller fra deg. Når selskapet ditt forlater chatten, opphører tillatelsen av seg selv.

Produkter fra ditt eget katalog

Når du har lastet opp varekatalogen, tilbyr byggeren en produktvelger-blokk. Det er ingen alternativer å vedlikeholde: listen er katalogen din. Den som bestiller søker i den, ser bildet, navnet og varenummeret, og backenden din mottar varenummeret. Skava avviser et nummer som ikke finnes i katalogen din. For mengden, legg et vanlig tallfelt ved siden av.

Definer kortet selv

Backenden din bestemmer hva kortet sier. Skava sjekker bare form, størrelse og sikkerhet, aldri betydning: den kjenner verken ordretilstander eller feltnavn. For å gjø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 må være heltallet 1. Uten dette teller ikke svaret som et kort, og responsmappingen konfigurert i elementet gjelder.
• state er kun farge og ikon: ok, pending, warn eller error. Alt som bærer mening settes inn i status_text som fri tekst.
• fields er en liste med etiketter og verdier, maksimalt 20 poster. Verdier som er for lange forkortes i stedet for å avvises, så en ordre mislykkes aldri på grunn av en detalj.

Brukerens inndata tilhører serveren: de forblir urørte uansett hva bakenden sender. De er opptaket i chatten over hva som faktisk ble sendt inn.

Rapportere status senere

Når elementet kjører, sender Skava to ekstra verdier: callback_url og callback_token. Rapportér en ny status der senere, og et nytt kort vises i chatten, også på telefonen, mens noen ser på. Det forrige forblir, slik at det er mulig å se hvilken status som ble rapportert. Send samme card-objekt som over, via POST med headeren Authorization: Bearer <callback_token>. Tre valgfrie verdier settes ved siden av kortet:

• seq: din egen teller. En rapport med en lavere eller lik verdi forkastes, slik at to rapporter ikke kan overhale hverandre.
• final: avslutter interaksjonen. Tokenet blir ugyldig og kortet er endelig.
• notify: sett til false for å poste kortet stille, uten antall ulest og uten varsel. For mellomsteg som ikke bør vekke noen. Uten dette er kortet en helt vanlig melding.

En interaksjon kan poste maksimalt 50 kort. Den samme rapporten to ganger gir ikke et annet kort.

Skava svarer med 200 og en liste over hints hvis noe ble forkortet eller droppet, og med 422 hvis kortet var ubrukelig. En interaksjon aksepterer rapporter i 90 dager.

Kortene sendes av Skavas systemavsender, ikke av personen som kjørte elementet, og ikke av en konto i ditt eget selskap. Hvilket system som skriver, står i kortets tittel.

Et komplett eksempel du kan kopiere finnes i repositoriet under example_order_server/ og kjører på api.skava.io.

Relatert

Vil du i stedet lage en utfyllbar dokumentmal? Se Custom Elements: Dokumenter.

Ofte stilte spørsmål