Tilpassede elementer: API

En API-grensesnitt er et skjema der fylte verdier Skava sender 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 inntastingsfelter (de danner JSON), måladressen og autentisering.

1. Opprett felt: Hvert felt får en JSON-nøkkel. Til høyre ser du i sanntid JSON-forhåndsvisningen, som sendes til din backend akkurat slik.
2. Adresse (URL): https://-adressen til din backend. 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ørringsparametere i stedet for å sendes i kroppen.
4. Godkjenning: Sett navnet på overskriften (f.eks. Authorization) og prefikset for verdien (f.eks. Bearer ), og lagre deretter tokenet. Du kan også angi en utløpsdato.
5. Svarfelt (valgfritt): Definer via sti hvilke verdier fra backend-svaret 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 kun om et token er satt og når det utløper. Ved sending legger Skava til tokenet på serversiden i den konfigurerte overskriften. Hvis du setter en utløpsdato, nekter Skava å utføre kall etter utløpet og ber deg fornye tokenet.

Testing: Ping og testforespørsel

• Ping : en enkel tilgjengelighetskontroll. Den sjekker kun om adressen din svarer, og sender ikke token eller skjema-data i prosessen. Viser tilgjengelighet, status og svaretid. Ideelt som første steg.
• Testforespørsel : den faktiske prøveløp: sender eksempeldata inkludert token til adressen din og viser deg det komplette svaret samt de uttrukne svarsfeltene.

Som administrator kan du kjøre begge 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, gir du det ut med Utgiv.

Sikkerhet

Hvordan teamet bruker en utgitt grensesnitt

Når et grensesnitt er utgitt, kan alle medlemmer i bedriften utløse det direkte fra en chat: ingen redigeringsverktøy trengs. Flyten er den samme som med dokumentmaler: velg, fyll ut, send.

1. I chatten, trykk på Plus nederst og velg Egendefinert element.
2. Velg ønsket mal eller grensesnitt fra listen.
3. Fyll ut skjemaet og Send.
4. Resultatet vises som et kort i chatten: synlig for alle i chatten.

La AI bygge et element

Som selskapsadministrator trenger du ikke bruke redigereren selv. Si til Skava-assistenten i chatten, for eksempel «lag en bestillingsskjema for katalogen min med mengde og leveringsadresse». Den lager et utkast ut fra det, kan endre felt ett etter ett senere, og den kjenner din opplastede artikkelkatalog: for bestillinger foreslår den produktvelgeren i stedet for et tekstfelt for artikkelnummeret.

Hva den også kan sette: endepunkt og metode samt tilhørighet («kun selskapsmedlemmer» eller «også utenforstående i samme chat»). For tilhørigheten spør den først i stedet for bare å sette den, fordi den avgjør hvem som kan kjøre noe fra utsiden.

Hva den eksplisitt ikke berører: tilgangstokenet. Den ber aldri om ett og aksepterer aldri ett, fordi chatmeldinger lagres. Du setter det inn selv i redigereren, ellers blir ingen kall sendt ut. Og den kan ikke publisere: det siste steget står igjen hos deg, slik at ingenting blir synlig for kunder uten sjekk.

Hvem kan kjøre det

Fanen «Endepunkt» sier hvem som kan bruke et element. Standardinnstillingen er medlemmene i ditt selskap. Den andre innstillingen åpner det for utenforstående, men kun i en chat hvor noen fra ditt selskap også er til stede: akkurat tilfellet det er ment for, når kunden bestiller fra deg. Når ditt selskap forlater chatten, opphører tillatelsen automatisk.

Produkter fra din egen katalog

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

Definer kortet selv

Din backend bestemmer hva kortet sier. Skava sjekker bare form, størrelse og sikkerhet, aldri betydning: den kjenner verken bestillingsstater 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 det teller svaret ikke som et kort, og responskartleggingen som er konfigurert i elementet, gjelder.
• state er kun farge og ikon: ok, pending, warn eller error. Alt som bærer mening hører hjemme i status_text som fri tekst.
• fields er en liste over etikett og verdi, maksimalt 20 oppføringer. Verdier som er for lange blir forkortet i stedet for avvist, slik at en bestilling aldri feiler på grunn av en detalj.

Brukerens inndata tilhører serveren: de forblir uendret uavhengig av hva din backend sender. De er protokollen 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 følger etter kortet:

• seq: din egen teller. En rapport med en mindre eller lik verdi blir forkastet, slik to rapporter ikke kan overhente hverandre.
• final: avslutter interaksjonen. Tokenet blir ugyldig og kortet er ferdig.
• notify: sett til false for å poste kortet stille, uten antall uläste og uten varsling. For mellomtrinn som ikke skal 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 nytt 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 blir publisert 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 arkivet under example_order_server/ og kjører på api.skava.io.

Relatert

Vil du i stedet bygge et utfyllbart dokumentmal? Se Custom Elements: Dokumenter.

Ofte stilte spørsmål