Aangepaste elementen: API

Een API-interface is een formulier waarvan de ingevulde waarden Skava als JSON naar een door jou opgegeven adres (je backend) stuurt. Zo kun je Skava veilig koppelen aan je eigen systemen.

Een API-interface instellen

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

1. Velden aanmaken: Elk veld krijgt een JSON-sleutel. Rechts zie je live de JSON-voorbeeldweergave, die 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 de body te verzenden.
4. Authenticatie: Stel de headernaam (bijv. Authorization) en de waardeprefix (bijv. Bearer ) in en bewaar de token. Stel optioneel een vervaldatum in.
5. Responsvelden (optioneel): Definieer via pad welke waarden uit de backendrespons moeten worden weergegeven: bijv. order.id of items[0].sku.
6. Controleer met Ping en Test Request, en publiceer daarna met Release.

Token veilig opslaan

De token wordt versleuteld opgeslagen en nooit aan klanten teruggegeven: de app toont alleen of er een token is ingesteld en wanneer deze verloopt. Bij het verzenden voegt Skava deze server-side toe aan de geconfigureerde header. Als u een vervaldatum instelt, weigert Skava de oproep na verloop en vraagt u de token te vernieuwen.

Testen: Ping en Testverzoek

• Ping: een lichte bereikbaarheidscontrole. Hij controleert alleen of je adres reageert en stuurt daarbij geen token of formulierdata. Toont bereikbaarheid, status en responstijd. Ideaal als eerste stap.
• Testverzoek: de echte proefloop: stuurt voorbeelddata inclusief token naar je adres en toont zowel de volledige respons als de geëxtraheerde responsvelden.

Als beheerder kun je beide uitvoeren terwijl je nog in conceptmodus bent, om de integratie te verifiëren vóór de release.

Concept en publicatie

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

Beveiliging

Hoe het team een vrijgegeven interface gebruikt

Zodra een interface is vrijgegeven, kunnen alle leden van het bedrijf deze direct vanuit een chat activeren, zonder editor. Er is geen gezamenlijke invoer en geen tussenschakelend dialoogvenster: elk vrijgegeven element staat in het plusmenu onder zijn eigen naam, met het logo van het bedrijf dat het aanbiedt.

1. Tik in de chat op Plus onderaan en tik op het element dat je wilt, bijvoorbeeld Materialen bestellen.
2. Vul het formulier in en tik op Versturen.
3. 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. Vertel de Skava-assistent in de chat bijvoorbeeld: "Maak een bestelformulier voor mijn catalogus met hoeveelheid en leveradres". De assistent maakt daar een concept van, kan velden later één voor één aanpassen en kent uw geüploade artikelcatalogus: bij bestellingen suggereert hij de productkiezer in plaats van een tekstveld voor het artikelnummer.

Wat hij ook kan instellen: endpoint en methode evenals de doelgroep ("alleen bedrijfsleden" of "ook buitenstaanders in dezelfde chat"). Voor de doelgroep vraagt hij eerst, in plaats van het direct in te stellen, omdat dit bepaalt wie iets van buitenaf mag uitvoeren.

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

Wie het mag uitvoeren

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

Producten uit je eigen catalogus

Zodra je je artikelcatalogus hebt geüpload, biedt de bouwer een productkeuze-blok aan. Er zijn geen opties te onderhouden: de lijst is je catalogus. De besteller zoekt erin, ziet de afbeelding, de naam en het artikelnummer, en je backend ontvangt het artikelnummer. Skava wijst een nummer af dat niet in je catalogus staat. Voor de hoeveelheid, plaats een gewoon getalveld ernaast.

Bepaal de kaart zelf

Je backend bepaalt wat de kaart zegt. Skava controleert alleen vorm, grootte en veiligheid, nooit de betekenis: het kent noch bestelstatussen noch veldnamen. Om dat te doen, antwoord 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 only colour and icon: ok, pending, warn or error. Anything that carries meaning goes into status_text as free text.
• fields is een lijst van labels en waarden, met maximaal 20 items. Waarden die te lang zijn, worden ingekort in plaats van afgewezen, zodat een bestelling nooit mislukt om een detail.

De invoer van de gebruiker hoort bij de server: deze blijft ongewijzigd, ongeacht wat uw backend stuurt. Het is het bewijs in de chat van wat daadwerkelijk is ingediend.

Status later melden

Wanneer het element wordt uitgevoerd, stuurt 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 je kunt zien welke status is gemeld. Stuur 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 verwerpt, zodat twee rapporten elkaar niet kunnen inhalen.
• final: sluit de interactie af. Het token wordt ongeldig en de kaart is definitief.
• notify: stel dit in op false om de kaart stil te posten, zonder ongelezen-teller en zonder melding. Voor tussenschappen die niemand moeten wakker maken. Zonder deze instelling is de kaart een volwaardig bericht.

Een interactie kan maximaal 50 kaarten posten. Het tweemaal versturen van hetzelfde rapport levert geen tweede kaart op.

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

De kaarten worden verzonden door de systeemafzender 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 afzender is.

Een volledig voorbeeld om te kopiëren staat in de repository onder example_order_server/ en draait op api.skava.io.

Gerelateerd

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

Veelgestelde vragen