Custom Elements: API-Schnittstellen

Eine API-Schnittstelle ist ein Formular, dessen ausgefüllte Werte Skava als JSON an eine von dir hinterlegte Adresse (dein Backend) sendet. So verbindest du Skava sicher mit eigenen Systemen.

Eine API-Schnittstelle einrichten

Eine Schnittstelle besteht aus den Eingabefeldern (sie ergeben das JSON), der Zieladresse und der Authentifizierung.

1. Felder anlegen: Jedes Feld bekommt einen JSON-Key. Rechts siehst du live die JSON-Vorschau, die genau so an dein Backend gesendet wird.
2. Adresse (URL): die https://-Adresse deines Backends. Nur HTTPS und öffentlich erreichbare Adressen sind erlaubt (siehe Sicherheit unten).
3. Methode: POST (Standard), PUT, PATCH oder GET. Bei GET werden die Werte als Query-Parameter angehängt statt im Body gesendet.
4. Authentifizierung: Header-Name (z. B. Authorization) und Wert-Präfix (z. B. Bearer ) festlegen, dann den Token speichern. Optional ein Ablaufdatum setzen.
5. Antwort-Felder (optional): Lege per Pfad fest, welche Werte aus der Backend-Antwort angezeigt werden — z. B. order.id oder items[0].sku.
6. Mit Ping und Test-Request prüfen, dann Freigeben.

Token sicher hinterlegen

Der Token wird verschlüsselt gespeichert und nie an Clients zurückgegeben — die App zeigt nur, ob ein Token gesetzt ist und wann er abläuft. Beim Senden hängt Skava ihn serverseitig an den konfigurierten Header. Setzt du ein Ablaufdatum, verweigert Skava den Aufruf nach Ablauf und bittet dich, den Token zu erneuern.

Testen: Ping und Test-Request

• Ping — ein leichter Erreichbarkeits-Check. Er prüft nur, ob deine Adresse antwortet, und sendet dabei weder Token noch Formulardaten. Zeigt Erreichbarkeit, Status und Antwortzeit. Ideal als erster Schritt.
• Test-Request — der echte Probelauf: sendet Beispieldaten inklusive Token an deine Adresse und zeigt dir die vollständige Antwort sowie die ausgelesenen Antwort-Felder.

Als Admin kannst du beides schon im Entwurf ausführen, um die Anbindung vor der Freigabe zu prüfen.

Entwurf und Freigabe

Jede Schnittstelle ist zuerst ein Entwurf und lässt sich frei bearbeiten. Sobald alles passt, gibst du sie mit Freigeben frei.

Sicherheit

So nutzt das Team eine freigegebene Schnittstelle

Sobald eine Schnittstelle freigegeben ist, lösen alle Firmen-Mitglieder sie direkt aus einem Chat aus — ganz ohne Editor. Der Ablauf ist derselbe wie bei Dokument-Vorlagen: auswählen, ausfüllen, senden.

1. Im Chat unten auf Plus tippen und Custom-Element wählen.
2. Aus der Liste die gewünschte Vorlage bzw. Schnittstelle auswählen.
3. Das Formular ausfüllen und Senden.
4. Das Ergebnis erscheint als Karte im Chat — sichtbar für alle im Chat.

Ein Element von der KI bauen lassen

Als Firmen-Admin musst du den Editor nicht selbst bedienen. Sag es dem Skava-Assistenten im Chat, zum Beispiel „bau mir eine Bestellmaske für meinen Katalog mit Menge und Lieferadresse". Er legt daraus einen Entwurf an, kann Felder später einzeln ändern, und er kennt deinen hochgeladenen Artikelkatalog: für Bestellungen schlägt er die Produktauswahl vor statt eines Textfeldes für die Artikelnummer.

Was er außerdem setzen darf: Endpunkt und Methode sowie die Freigabe („nur Mitarbeiter" oder „auch Externe im selben Chat"). Bei der Freigabe fragt er nach, statt sie einfach zu setzen, denn sie entscheidet, wer von außen etwas auslösen darf.

Was er ausdrücklich nicht tut: das Zugangstoken anfassen. Er fragt nicht danach und nimmt keines entgegen, denn Chat-Nachrichten werden gespeichert. Das trägst du selbst im Editor ein, sonst läuft kein Aufruf. Und veröffentlichen kann er nicht: der letzte Schritt bleibt bei dir, damit nichts ungeprüft für Kunden sichtbar wird.

Wer darf auslösen

Im Reiter „Endpunkt" steht, wer ein Element benutzen darf. Standard sind die Mitarbeiter deiner Firma. Die zweite Einstellung öffnet es für Externe, allerdings nur in einem Chat, in dem auch jemand aus deiner Firma sitzt: genau der Fall, für den es gedacht ist, nämlich der Kunde, der bei dir bestellt. Verlässt deine Firma den Chat, endet die Freigabe von selbst.

Produkte aus dem eigenen Katalog

Hast du deinen Artikelkatalog hochgeladen, kannst du im Baukasten den Baustein Produktauswahl verwenden. Er hat keine Optionen zu pflegen, die Auswahlliste ist dein Katalog: der Besteller sucht darin, sieht Bild, Bezeichnung und Artikelnummer, und an dein Backend geht die Artikelnummer. Skava lehnt eine Nummer ab, die nicht in deinem Katalog steht. Für die Menge nimmst du daneben ein normales Zahlenfeld.

Die Karte selbst bestimmen

Dein Backend darf sagen, was in der Karte steht. Skava prüft nur Form, Größe und Sicherheit, nie die Bedeutung: es kennt weder Bestellzustände noch Feldnamen. Antworte dafür mit einem Objekt card:

{"card": {"v": 1, "title": "Bestellung 10001", "state": "pending", "status_text": "Wird kommissioniert", "fields": [{"label": "Sendungsnummer", "value": "DPD123456789"}]}}

• v muss die Ganzzahl 1 sein. Fehlt sie, gilt die Antwort nicht als Karte und die im Element hinterlegte Antwort-Zuordnung greift.
• state ist nur Farbe und Symbol: ok, pending, warn oder error. Alles mit Bedeutung schreibst du als freien Text in status_text.
• fields ist eine Liste aus Beschriftung und Wert, höchstens 20 Einträge. Zu lange Werte werden gekürzt statt abgelehnt, damit eine Bestellung nicht an einer Kleinigkeit scheitert.

Die Eingaben des Nutzers gehören dem Server: sie bleiben unverändert stehen, egal was dein Backend schickt. Sie sind der Nachweis im Chat, was wirklich abgeschickt wurde.

Den Status später nachmelden

Beim Auslösen schickt Skava zwei zusätzliche Werte mit: callback_url und callback_token. Meldest du dort später einen neuen Stand, erscheint im Chat eine neue Karte, auch auf dem Handy, während jemand hinsieht. Die vorige bleibt stehen, damit ablesbar ist, wann welcher Stand gemeldet wurde. Geschickt wird dasselbe card-Objekt wie oben, per POST mit dem Kopf Authorization: Bearer <callback_token>. Dazu drei optionale Werte neben der Karte:

• seq: dein eigener Zähler. Eine Meldung mit kleinerem oder gleichem Wert wird verworfen, damit sich zwei Meldungen nicht überholen.
• final: schließt den Vorgang. Danach ist das Token ungültig und die Karte fest.
• notify: mit false wird die Karte still eingestellt, also ohne Ungelesen-Zähler und ohne Benachrichtigung. Für Zwischenschritte, die niemanden aufwecken sollen. Ohne die Angabe ist es eine ganz normale Nachricht.

Ein Vorgang darf höchstens 50 Karten stellen. Dieselbe Meldung zweimal ergibt keine zweite Karte.

Skava antwortet mit 200 und einer Liste hints, wenn etwas gekürzt oder verworfen wurde, und mit 422, wenn die Karte unbrauchbar war. Ein Vorgang nimmt 90 Tage lang Meldungen an.

Gepostet werden die Karten vom Systemabsender von Skava, nicht von der Person, die ausgelöst hat, und auch nicht von einem eigenen Konto deiner Firma. Wessen System schreibt, steht im Titel der Karte.

Ein vollständiges Beispiel zum Abschreiben liegt im Repository unter example_order_server/ und läuft unter api.skava.io.

Verwandt

Du willst stattdessen eine ausfüllbare Dokument-Vorlage bauen? Siehe Custom Elements: Dokumente.

Häufige Fragen