Skava Skava / Wiki

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.

i

API-Schnittstellen verwaltest du in der Webapp unter Custom Elements → Umschalter API-Schnittstellen. Anlegen und Bearbeiten ist Firmen-Admins vorbehalten; freigegebene Schnittstellen können dann alle Mitglieder der Firma auslösen.

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.

!

Freigegebene Schnittstellen sind unveränderlich. Das ist gewollt: So kann nach der Freigabe niemand mehr heimlich die Zieladresse oder den Token austauschen. Möchtest du etwas ändern, lege eine neue Version an.

Sicherheit

i

Damit die Schnittstelle nicht missbraucht werden kann, gelten feste Regeln: Es sind nur HTTPS-Adressen erlaubt, und die Adresse muss auf eine öffentliche Zieladresse zeigen — interne Adressen (z. B. localhost, private Netze oder Cloud-Metadaten) werden abgelehnt. Skava prüft das bei jedem Aufruf, verbindet sich exakt zur geprüften Adresse, folgt keinen Weiterleitungen und begrenzt Zeitlimit und Antwortgröße.

Verwandt

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

Häufige Fragen

Was ist eine API-Schnittstelle in Skava?

Ein Formular, dessen ausgefüllte Werte Skava als JSON an eine von dir hinterlegte https://-Adresse (dein Backend) sendet — praktisch, um Skava mit eigenen Systemen zu verbinden.

Wer darf API-Schnittstellen anlegen und auslösen?

Anlegen und Bearbeiten ist Firmen-Admins vorbehalten. Eine freigegebene Schnittstelle können anschließend alle Mitglieder der Firma auslösen.

Was ist der Unterschied zwischen „Ping“ und „Test-Request“?

Ping prüft nur, ob die Adresse erreichbar ist — ohne Token und ohne Daten. Test-Request sendet Beispieldaten inklusive Token und zeigt die vollständige Antwort.

Ist mein API-Token sicher?

Ja. Der Token wird verschlüsselt gespeichert und nie an Clients ausgeliefert. Die App zeigt nur, ob ein Token gesetzt ist und wann er abläuft.

Welche Adressen sind als Endpunkt erlaubt?

Nur öffentlich erreichbare https://-Adressen. Interne Ziele wie localhost, private Netze oder Cloud-Metadaten werden abgelehnt — das schützt vor Missbrauch der Schnittstelle.

Warum kann ich eine freigegebene Schnittstelle nicht mehr ändern?

Freigegebene Schnittstellen sind bewusst unveränderlich — so kann nach der Freigabe niemand mehr Zieladresse oder Token austauschen. Für Änderungen legst du eine neue Version an.