Aangepaste elementen: API

Een API-interface is een formulier waarvan de ingevulde waarden Skava als JSON verzendt naar een door u opgegeven adres (uw backend). Zo kunt u Skava veilig koppelen aan uw eigen systemen.

Een API-interface instellen

Een interface bestaat uit invoervelden (ze vormen de JSON), het doeladres en authenticatie.

1. Velden aanmaken: Elk veld krijgt een JSON-sleutel. Rechts zie je live de JSON-voorbeeldweergave, die exact op deze manier naar je backend wordt verzonden.
2. Adres (URL): het https://-adres van je backend. Alleen HTTPS-adressen en publiek toegankelijke adressen zijn toegestaan (zie Beveiliging hieronder).
3. Methode: POST (standaard), PUT, PATCH of GET. Bij GET worden de waarden als queryparameters toegevoegd in plaats van in het berichtlichaam te worden verzonden.
4. Authenticatie: Stel de header-naam in (bijv. Authorization) en de waarde-prefix (bijv. Bearer ), en sla de token op. Optioneel kun je een vervaldatum instellen.
5. Antwoordvelden (optioneel): Definieer via een pad welke waarden uit het backend-antwoord moeten worden weergegeven: bijv. order.id of items[0].sku.
6. Controleer met Ping en Test Request, en klik vervolgens op Release.

Token veilig opslaan

Het token wordt versleuteld opgeslagen en nooit naar clients teruggegeven: de app toont alleen of er een token is ingesteld en wanneer het verloopt. Bij verzending voegt Skava het server-side toe aan de geconfigureerde header. Als u een vervaldatum instelt, weigert Skava de oproep na verloop van tijd en vraagt u om het token te vernieuwen.

Testen: Ping en Testaanvraag

• Ping : een lichte bereikbaarheidstest. Deze controleert alleen of uw adres reageert en verzendt geen token of formuliergegevens. Toont bereikbaarheid, status en responstijd. Ideaal als eerste stap.
• Testaanvraag : de echte proefdraai: verzendt voorbeeldgegevens inclusief token naar uw adres en toont de volledige reactie evenals de geëxtraheerde reactievelden.

Als beheerder kunt u beide uitvoeren terwijl u nog in conceptmodus bent om de integratie te verifiëren voordat u deze vrijgeeft.

Concept en publiceren

Elk interface begint als een concept en kan vrij worden bewerkt. Zodra alles klaar is, publiceer je het met Publiceren.

Beveiliging

Hoe het team een vrijgegeven interface gebruikt

Zodra een interface is vrijgegeven, kunnen alle teamleden deze direct vanuit een chat activeren: geen editor nodig. De werkwijze is hetzelfde als bij documenttemplates: selecteren, invullen, verzenden.

1. Tik in de chat op Plus onderaan en kies Aangepast element.
2. Kies de gewenste sjabloon of interface uit de lijst.
3. Vul het formulier in en tik op Verzenden.
4. Het resultaat verschijnt als kaart in de chat: zichtbaar voor iedereen in de chat.

Laat de AI een element bouwen

Als bedrijfsbeheerder hoeft u de editor niet zelf te gebruiken. Vraag de Skava-assistent in de chat, bijvoorbeeld "maak een bestelformulier voor mijn assortiment met hoeveelheid en leveringsadres". Het maakt daar een concept van, kan later velden één voor één aanpassen en kent uw geüploade artikelcatalogus: voor bestellingen stelt het de productkiezer voor in plaats van een tekstveld voor het artikelnummer.

Wat het ook kan instellen: endpoint en methode evenals het publiek ("alleen leden van het bedrijf" of "ook buitenstaanders in dezelfde chat"). Voor het publiek vraagt het eerst in plaats van het direct in te stellen, omdat het bepaalt wie iets van buitenaf kan uitvoeren.

Wat het expliciet niet aanraakt: de toegangstoken. Het vraagt er nooit om en accepteert er nooit een, omdat chatberichten worden opgeslagen. U voert deze zelf in de editor in, anders wordt er geen oproep verzonden. En het kan niet publiceren: de laatste stap blijft bij u, zodat er niets ongecontroleerd zichtbaar wordt voor klanten.

Wie het mag uitvoeren

Het tabblad "Endpoint" geeft aan wie een element mag gebruiken. De standaard is de leden van uw bedrijf. De tweede instelling opent het voor buitenstaanders, maar alleen in een chat waar ook iemand van uw bedrijf aanwezig is: precies het geval waarvoor het bedoeld is, de klant die bij u bestelt. Wanneer uw bedrijf de chat verlaat, vervalt de machtiging automatisch.

Producten uit uw eigen assortiment

Zodra u uw artikelcatalogus hebt geüpload, biedt de builder een productkiezer-blok. Er zijn geen instellingen te onderhouden: de lijst is uw catalogus. De bestellende persoon zoekt erin, ziet de afbeelding, naam en artikelnummer, en uw backend ontvangt het artikelnummer. Skava verwijst een nummer dat niet in uw catalogus staat. Voor de hoeveelheid plaatst u gewoon een getallenveld ernaast.

Definieer de kaart zelf

Uw backend bepaalt wat de kaart zegt. Skava controleert alleen vorm, formaat en veiligheid, nooit betekenis: het kent noch bestelstatussen noch veldnamen. Om dat te doen, antwoordt u met een card-object:

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

• v moet het gehele getal 1 zijn. Zonder dit telt het antwoord niet als een kaart en wordt de in het element geconfigureerde responsmapping toegepast.
• state is alleen kleur en icoon: ok, pending, warn of error. Alles met betekenis komt in status_text als vrije tekst.
• fields is een lijst van label en waarde, maximaal 20 items. Waarden die te lang zijn, worden ingekort in plaats van afgewezen, zodat een bestelling nooit faalt door een detail.

De invoer van de gebruiker is eigendom van de server: deze blijft ongewijzigd, ongeacht wat uw backend verzendt. Het is het verslag in de chat van wat er daadwerkelijk is ingediend.

Status later melden

Wanneer het element wordt uitgevoerd, verzendt Skava twee extra waarden: callback_url en callback_token. Meld daar later een nieuwe status en er verschijnt een nieuwe kaart in de chat, ook op de telefoon, terwijl iemand kijkt. De vorige blijft staan, zodat leesbaar is welke status is gemeld. Verstuur hetzelfde card-object als hierboven, via POST met de header Authorization: Bearer <callback_token>. Drie optionele waarden gaan naast de kaart:

• seq: uw eigen teller. Een rapport met een kleinere of gelijke waarde wordt genegeerd, zodat twee rapporten elkaar niet kunnen inhalen.
• final: sluit de interactie af. Het token wordt ongeldig en de kaart is definitief.
• notify: stel op false om de kaart stil te plaatsen, zonder onlezenaantal en zonder melding. Voor tussenstappen die niemand moeten wekken. Zonder deze optie is de kaart een volkomen normale bericht.

Een interactie kan maximaal 50 kaarten plaatsen. Dezelfde rapport twee keer sturen produceert geen tweede kaart.

Skava antwoordt met 200 en een lijst van hints als er iets is verkort of weggelaten, en met 422 als de kaart onbruikbaar was. Een interactie accepteert rapporten gedurende 90 dagen.

De kaarten worden geplaatst door de systeemzender van Skava, niet door de persoon die het element heeft uitgevoerd en niet door een account van uw eigen bedrijf. In de titel van de kaart staat welk systeem de tekst heeft geschreven.

Een compleet voorbeeld om te kopiëren, vindt u in de repository onder example_order_server/ en draait op api.skava.io.

Gerelateerd

Wilt u liever een invulbaar documenttemplate maken? Bekijk Custom Elements: Documenten.

Veelgestelde vragen