...
Stand: 11.11.2026, Release 9.3.
Anwendung
Diese Seite zeigt, wie Sie als Administrator eines Mandanten Schnittstellen, Keystores und Transaktionen erfassen und pflegen. Das Grundkonzept steht auf der Seite Schnittstellen-Verwaltung.
Voraussetzung ist die Rolle Administrator. In der Administration finden Sie die Unit «Schnittstellen» mit drei Einträgen:
| Eintrag | Inhalt |
|---|---|
| Übersicht | Die Schnittstellen Ihres Mandanten: Adresse, Art der Anmeldung, Zugangsdaten. |
| Keystores | Zertifikatsdateien mit ihrem Passwort, die Schnittstellen verwenden. |
| Transaktionen | Die Aufrufe, die über eine Schnittstelle laufen. |
...
Schnittstellen
Die Übersicht
Die Liste zeigt beim Öffnen alle Schnittstellen Ihres Mandanten und die Schnittstellen übergeordneter Mandanten, die für Sie freigegeben sind.
| Spalte | Bedeutung |
|---|---|
| Service-Key | Der eindeutige Schlüssel der Schnittstelle. Transaktionen und Formulare verwenden ihn als Verweis. |
| Aktiv | Ampel: aktiv oder deaktiviert. |
| Service-Typ, Auth-Typ | Art der Schnittstelle und Art der Anmeldung, als Symbol mit Text beim Überfahren. |
| Secrets | Anzahl der hinterlegten Zugangsdaten und Keystores. Ein Klick zeigt, welche es sind, nie ihren Wert. |
| URL | Die Adresse des Drittsystems. |
| Herkunft | «eigen» oder der Name des übergeordneten Mandanten. Der Zusatz «(überdeckt)» bedeutet: Ihr Mandant hat eine eigene Schnittstelle mit demselben Schlüssel, und diese gilt. |
| Freigabe | Symbol, wenn die Schnittstelle für untergeordnete Mandanten freigegeben ist. |
| Letzte Anpassung | Zeitpunkt der letzten Änderung. |
Die Suchmaske filtert nach Service-Key, Service-Typ, Auth-Typ, Aktiv, URL und Beschreibung. Die Spalte «Beschreibung» lässt sich über die Spaltenauswahl einblenden.
Schnittstellen eines übergeordneten Mandanten erscheinen grau. Sie können sie öffnen, aber nicht ändern.
Schnittstelle erfassen
- In der Übersicht eine neue Schnittstelle anlegen.
- Service-Key, Service-Typ und Auth-Typ wählen. Je nach Auth-Typ erscheinen weitere Felder.
- URL und die Angaben zur Anmeldung ausfüllen.
- Die Zugangsdaten setzen, siehe «Zugangsdaten setzen».
- «Speichern».
| Info | ||
|---|---|---|
| ||
Nach dem ersten Speichern ist die Schnittstelle aktiv. Sie muss deshalb beim ersten Speichern vollständig sein, einschliesslich der Zugangsdaten. |
Felder
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Service-Key | ✔ | 1 bis 128 Zeichen aus Buchstaben, Ziffern, _, - und .. Im Mandanten eindeutig, ohne Rücksicht auf Gross- und Kleinschreibung. Nach dem Anlegen nicht mehr änderbar. |
| Für Untermandanten freigegeben | ❌ | Gibt die Schnittstelle an untergeordnete Mandanten frei. Diese sehen sie schreibgeschützt und können sie verwenden. |
| Service-Typ | ✔ | REST, SOAP, Dateisystem oder LDAP. |
| Auth-Typ | ✔ | Die Art der Anmeldung, siehe nächste Tabelle. |
| URL | ❌ | Adresse des Drittsystems, höchstens 1'024 Zeichen. |
| Transformation | ❌ | Verweis auf eine Transformation, höchstens 512 Zeichen. |
| Beschreibung | ❌ | Freier Text, höchstens 255 Zeichen. |
| Implementation | ❌ | Java-Klasse, Generisch REST oder Generisch SOAP. Ohne Auswahl gilt der Standard des Service-Typs. |
| Java-Klasse | ❌ | Name der Klasse. Erscheint nur bei der Implementation «Java-Klasse». |
| Notiz | ❌ | Interne Notiz zur Schnittstelle. |
| Statische Header | ❌ | Liste aus Name und Wert. Die Header werden bei jedem Aufruf mitgesendet. |
| Properties | ❌ | Liste aus Name und Wert für weitere Einstellungen der Schnittstelle. |
| Client-Keystore, Truststore | ❌ | Im Abschnitt «Keystores», siehe «Keystore zuordnen». |
Anmerkung: Header und Properties dürfen keine Zugangsdaten enthalten. Ein Name, der wie ein Passwort oder Schlüssel aussieht, wird beim Speichern abgewiesen, ebenso der Header Authorization. Zugangsdaten gehören in die Zeile des Auth-Typs.
Auth-Typen
| Auth-Typ | Zusätzliche Felder | Zugangsdaten |
|---|---|---|
| Keine Anmeldung | keine | keine |
| Basic (Benutzer und Passwort) | Benutzername (Pflicht), Token-URL (falls das Drittsystem eine eigene Login-Adresse hat) | Passwort |
| API-Key | Header des API-Keys (Standard X-API-Key) | API-Key |
| Bearer-Token | keine | Bearer-Token |
| OAuth 2.0 Client Credentials | Token-URL und Client-ID (Pflicht), Scope, Anmeldung am Token-Endpoint (Standard BODY), Feld des Access-Tokens (Standard access_token), Feld der Gültigkeit (Standard expires_in) | Client-Secret |
| SOAP (Benutzer und Passwort) | Benutzername (Pflicht) | SOAP-Passwort |
| Signaturschlüssel (Java-Klasse signiert selbst) | Nur mit der Implementation «Java-Klasse» | Signaturschlüssel |
Anmerkung: Der Service-Typ LDAP lässt nur «Keine Anmeldung» und «Basic» zu. Die Pflichtangaben eines Auth-Typs gelten für eine aktive Schnittstelle; eine deaktivierte darf unvollständig sein.
Zugangsdaten setzen
Die Zeile der Zugangsdaten zeigt nur den Zustand, nie den Wert: «nicht gesetzt», «gesetzt, geändert … von …» oder «neuer Wert gesetzt».
- In der Zeile auf das Stift-Symbol «Neuen Wert setzen …» klicken.
- Im Dialog den Wert in «Neuer Wert» und nochmals in «Wert wiederholen» eingeben.
- «Übernehmen». Die Zeile zeigt «neuer Wert gesetzt».
- Die Schnittstelle speichern. Erst jetzt wird der Wert verschlüsselt abgelegt.
| Warnung | ||
|---|---|---|
| ||
Bewahren Sie Zugangsdaten zusätzlich dort auf, wo Ihre Organisation Passwörter verwaltet. In der Schnittstellen-Verwaltung können Sie einen Wert überschreiben, aber nicht mehr anzeigen. Das Auge-Symbol «Anzeigen» steht nur berechtigten Support-Benutzern des Betreibers zur Verfügung; jede Anzeige wird protokolliert. |
Wenn Sie den Auth-Typ einer Schnittstelle wechseln, werden die bisherigen Zugangsdaten beim Speichern gelöscht.
Keystore zuordnen
Braucht das Drittsystem ein Client-Zertifikat, oder verwendet es ein Zertifikat, dem Ihr Server nicht von sich aus vertraut, ordnen Sie der Schnittstelle einen Keystore zu. Der Keystore muss vorher in der Liste «Keystores» erfasst sein.
| Feld | Beschreibung |
|---|---|
| Client-Keystore | Das Zertifikat, mit dem sich die Schnittstelle beim Drittsystem ausweist. |
| Truststore | Die Zertifikate, denen die Schnittstelle vertraut. Ohne Auswahl gelten die Zertifikate des Servers. |
Die Auswahl zeigt Name, Typ und Ablaufdatum jedes Keystores. Verwenden weitere Schnittstellen denselben Keystore, nennt das Formular sie unter «Keystores auch verwendet von».
Speichern, aktivieren, deaktivieren
| Knopf | Wirkung |
|---|---|
| Speichern | Speichert die Angaben und einen neu gesetzten Wert der Zugangsdaten. |
| Deaktivieren | Die Schnittstelle bleibt gespeichert, wird aber nicht mehr verwendet. Aufrufe über diesen Service-Key schlagen fehl, auch wenn ein übergeordneter Mandant eine Schnittstelle mit demselben Schlüssel freigegeben hat. |
| Aktivieren | Die Schnittstelle wird wieder verwendet. Sie muss dafür vollständig sein. |
Ist eine Angabe unzulässig oder fehlt eine Pflichtangabe, bleibt das Formular offen, und die Statuszeile nennt alle Gründe: «Die Schnittstelle kann nicht gespeichert werden: …».
Schnittstelle prüfen: Diagnose
Das Stethoskop-Symbol «Diagnose» in der Zeile einer Schnittstelle zeigt, was ein Formular oder eine Transaktion Ihres Mandanten mit diesem Service-Key tatsächlich erhält.
- Herkunft: die eigene Schnittstelle, eine freigegebene Schnittstelle eines übergeordneten Mandanten oder eine bisherige Konfigurationsdatei («Legacy-Datei»).
- Mandant: der Mandant, für den die Diagnose gilt.
- Typ, URL, Benutzername, Properties.
- Secrets: pro Zugangswert «lesbar» mit der Länge oder «nicht lesbar» mit dem Grund. Nie der Wert.
- Keystores: Name, Typ und Ablaufdatum.
Die Diagnose baut keine Verbindung zum Drittsystem auf. Sie prüft, ob die Angaben vollständig und die Zugangsdaten lesbar sind, nicht, ob das Drittsystem sie annimmt.
Schnittstelle löschen
- Die Schnittstelle öffnen und «Deaktivieren».
- In der Übersicht die Zeile ankreuzen und den Papierkorb wählen.
...
| Warnung | ||
|---|---|---|
| ||
Das System prüft nicht, ob eine Transaktion oder ein Formular den Service-Key noch verwendet. Nach dem Löschen schlagen solche Aufrufe fehl. |
...
Keystores
Ein Keystore ist eine Zertifikatsdatei zusammen mit ihrem Passwort. Sie erfassen ihn einmal und ordnen ihn beliebig vielen Schnittstellen zu. Läuft ein Zertifikat ab, ersetzen Sie die Datei an einer Stelle.
Die Liste
| Spalte | Bedeutung |
|---|---|
| Name | Der Name des Keystores. |
| Art | Client-Keystore oder Truststore. |
| Typ | Das Format der Datei: PKCS12, JKS oder JCEKS. Es wird aus der Datei erkannt. |
| Ablauf | Das früheste Ablaufdatum der enthaltenen Zertifikate. Orange: läuft in weniger als 30 Tagen ab. Rot: abgelaufen. |
| Verwendet von | Anzahl der Schnittstellen, die den Keystore verwenden. Ein Klick zeigt ihre Service-Keys. |
| Letzte Anpassung, Benutzer letzte Anpassung | Zeitpunkt und Benutzer der letzten Änderung. |
Die Liste zeigt nur die Keystores Ihres Mandanten. Keystores werden nicht an untergeordnete Mandanten weitergegeben.
Keystore erfassen
- In der Liste einen neuen Keystore anlegen.
- Name und Art wählen.
- In der Zeile «Datei» auf «Datei und Passwort hochladen …» klicken.
- Im Dialog zuerst die Datei wählen (
.p12,.pfx,.jksoder.jceks, höchstens 1'024 KB), dann das Passwort eingeben. Bei einem Truststore ist das Passwort freiwillig. - Der Dialog prüft die Datei sofort und zeigt ihre Einträge mit Ablaufdatum.
- «Übernehmen».
- Den Keystore speichern. Erst jetzt werden Datei und Passwort verschlüsselt abgelegt.
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Name | ✔ | Höchstens 128 Zeichen, im Mandanten eindeutig. |
| Art | ✔ | Client-Keystore oder Truststore. Nicht mehr änderbar, solange eine Schnittstelle den Keystore verwendet. |
| Beschreibung | ❌ | Freier Text, höchstens 255 Zeichen. |
| Datei | ✔ | Zeigt den Zustand: «keine Datei», Typ und Ablaufdatum der gespeicherten Datei oder «neue Datei: … – wird mit dem Speichern übernommen». |
| Verwendet von | – | Die Service-Keys der Schnittstellen, die den Keystore verwenden. Nur Anzeige. |
Hinweise der Prüfung
Lässt sich die Datei mit dem Passwort nicht öffnen, nimmt der Dialog sie nicht an: «Der Keystore lässt sich nicht öffnen: …».
Öffnet sich die Datei, zeigt der Dialog zusätzlich Warnungen. Sie verhindern das Speichern nicht, weisen aber auf ein Risiko hin. Die Warnungen erscheinen in englischer Sprache.
| Warnung (Auszug) | Bedeutung |
|---|---|
expires at …, in less than 30 days | Ein Zertifikat läuft bald ab. Besorgen Sie rechtzeitig ein neues. |
expired at … | Ein Zertifikat ist abgelaufen. Das Drittsystem wird die Verbindung ablehnen. |
protected with … | Die Datei ist mit einem veralteten Verfahren geschützt, zum Beispiel im Format JKS. |
key of … bits, at least … | Ein Schlüssel ist kürzer, als heute empfohlen wird. |
Zertifikat erneuern
- Den Keystore öffnen.
- «Datei und Passwort hochladen …» und die neue Datei mit ihrem Passwort angeben.
- Der Dialog nennt, für wie viele und welche Schnittstellen die neue Datei gelten wird.
- «Übernehmen» und den Keystore speichern.
Die neue Datei gilt danach für alle Schnittstellen, die den Keystore verwenden. Das Passwort lässt sich nur zusammen mit einer Datei setzen.
Keystore löschen
Ein Keystore lässt sich nur löschen, wenn ihn keine Schnittstelle mehr verwendet. Entfernen Sie zuerst die Zuordnung in den Schnittstellen. Datei und Passwort werden mitgelöscht.
...
Transaktionen
Eine Transaktion beschreibt, was beim Aufruf eines Drittsystems geschieht: eine geordnete Folge von Schritten. Jeder Schritt nennt eine Implementation und deren Eigenschaften. Die Zugangsdaten stehen nie in der Transaktion, sondern in der Schnittstelle, auf die sie verweist.
Die Liste
Die Liste zeigt die Transaktionen Ihres Mandanten mit ID und Name, UUID, Name sowie dem Zeitpunkt der Erstellung und der letzten Änderung. Die Suchmaske filtert nach ID und Name. Mit «Neues Element hinzufügen» legen Sie eine Transaktion an, mit «Öffnen» bearbeiten Sie eine bestehende.
Aufbau einer Transaktion
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Name | ✔ | Der Name, unter dem die Transaktion in Listen und Auswahlen erscheint. |
| Beschreibung | ✔ | Freier Text zum Zweck der Transaktion. |
| Transaktions-Schritte | ✔ | Mindestens ein Schritt. Die Schritte laufen in der Reihenfolge der Liste und lassen sich umsortieren. Ein Schritt kann Unterschritte haben. |
Jeder Schritt hat diese Felder:
| Feld | Pflicht | Beschreibung |
|---|---|---|
| ID | ❌ | Eine Kennung des Schritts. |
| Verhalten im Fehlerfall | ❌ | CONTINUE: Die Transaktion läuft nach einem Fehler dieses Schritts weiter. |
ROLLBACK: Ein Fehler dieses Schritts bricht die Transaktion ab; bricht sie später ab, wird dieser Schritt rückgängig gemacht, sofern seine Implementation das unterstützt. Ohne Wahl bricht ein Fehler die Transaktion ab. | |
| Implementation | ✔ |
| Die Klasse, die den Schritt ausführt. Die Auswahl zeigt alle verfügbaren Klassen mit ihrem vollständigen Namen. | ||
| Eigenschaften | ❌ | Liste der Einstellungen des Schritts, siehe unten. |
Eine Eigenschaft besteht aus:
| Feld | Beschreibung |
|---|---|
| Schlüssel | Der Name der Eigenschaft, zum Beispiel path. |
| Statischer Wert | Ein fester Wert. |
| Formel | Eine Formel, die den Wert zur Laufzeit berechnet. Sie hat Vorrang vor dem statischen Wert. |
| Typ | Der Datentyp als Java-Klasse, Standard ist java.lang.String (Text). Für Zahlen und Ja/Nein-Werte den passenden Typ wählen. |
| Referenzierte Eigenschaft | Verweis auf eine vordefinierte Eigenschaft einer Klasse. |
REST-Aufruf über eine Schnittstelle
Für einen REST-Aufruf besteht die Transaktion aus einem Rahmen und einem oder mehreren Unterschritten:
| Schritt | Implementation | Aufgabe |
|---|---|---|
| Rahmen | SequentialGenericRESTHandler | Stellt die Verbindung zur Schnittstelle her. |
| Unterschritt | GenericRESTJsonStepCommand | Ein Aufruf mit einer JSON-Antwort. |
| Unterschritt | GenericRESTJsonArrayStepCommand | Ein Aufruf, dessen Antwort eine JSON-Liste ist. |
| Unterschritt | GenericRESTMultipartStepCommand | Ein Aufruf, der eine Datei hochlädt. |
Der Rahmen verweist mit der Eigenschaft serviceId auf die Schnittstelle. Ihr Wert ist der Service-Key.
...
Aus der Schnittstelle kommen die Basis-URL, die Anmeldung, die statischen Header und, falls zugeordnet, das Client-Zertifikat. In der Transaktion steht nur, was den einzelnen Aufruf ausmacht.
Eigenschaften eines REST-Unterschritts
| Schlüssel | Standard | Beschreibung |
|---|---|---|
path | – | Wird an die URL der Schnittstelle angehängt. Platzhalter: ${xpath:/…} für einen Wert aus dem Formular, ${NAME} für eine Variable. |
httpMethod | POST | GET, POST, PUT, PATCH oder DELETE. |
queryParams, headers | – | Zusätzliche Parameter und Header als JSON-Objekt aus Name und Wert. Keine Zugangsdaten. |
transformOut, transformIn | – | Mapping vom Formular in die Anfrage bzw. von der Antwort ins Formular. |
requestContentType | application/json | Format der Anfrage. |
responseType | json | json, jsonarray oder text. |
expectedResponseCodes | 200 | Erwartete Statuscodes, zum Beispiel 200,201, 2xx oder 200-204. Jeder andere Code gilt als Fehler. |
retryCount, retryBackoffMillis | 0, 500 | Anzahl der Wiederholungen und Wartezeit dazwischen. |
connectTimeoutMillis, readTimeoutMillis | 10 und 30 Sekunden | Zeitlimiten für Verbindungsaufbau und Antwort. |
mode | normal | simulation: Die Anfrage wird vorbereitet und protokolliert, aber nicht gesendet. logging: Anfrage und Antwort werden protokolliert. Zugangsdaten stehen nie im Protokoll. |
| Warnung | ||
|---|---|---|
| ||
Die Eigenschaften |
Weitere Arten von Schritten
| Art | Implementation (Auswahl) | Hinweis |
|---|---|---|
| Generisch SOAP | Rahmen SequentialGenericWSDLHandler, Schritt GenericSOAPStepCommand | Verwendet keine Schnittstelle, sondern die Eigenschaft wsdlUrl, ohne Anmeldung. |
| Formulardaten | FormdataJSONTransactionStep, FormdataAttachmentsTransactionStep | Stellt die Daten und Beilagen des Formulars bereit. |
| Geschäftsverwaltung CMI | zum Beispiel CreateGeschaeft, FindGeschaeft, CreateOrUpdatePDF | Enthält der Name der Transaktion «CMI», wird sie als CMI-Export ausgeführt. |
| Initialisierung | InitSkribbleAPI, InitDeepSignAPI, InitHisoftApi, InitInnosolvApi | Bereitet die Verbindung zu einem bestimmten Dienst vor. |
Transaktion testen
Es gibt keinen Knopf, um eine Transaktion direkt auszuführen. Setzen Sie für einen Test die Eigenschaft mode auf simulation oder logging und lösen Sie die Transaktion über das Formular aus. Prüfen Sie vorher die Schnittstelle mit der Diagnose.
Transaktion auslösen
Eine Transaktion läuft, wenn ein Formular sie auslöst. Die Zuordnung geschieht im Service-Descriptor des Formulars, im Abschnitt «Schnittstellen»: Dort wählen Sie die Transaktion, aktivieren sie und legen fest, bei welchem Status sie läuft und welchen Status das Formular danach erhält.
Transaktion löschen
In der Liste die Zeilen ankreuzen und «Alle ausgewählten Einträge löschen» wählen. Das System prüft nicht, ob ein Formular die Transaktion noch verwendet.
...
Bekannte Probleme
«Die Schnittstelle kann nicht gespeichert werden: BASIC braucht ein Secret für BASIC_PW»
Problem
Die Schnittstelle ist aktiv, aber die Zugangsdaten sind nicht gesetzt. Die Meldung verwendet technische Namen: BASIC_PW ist das Passwort, API_KEY_VALUE der API-Key, OAUTH2_CLIENT_SECRET das Client-Secret.
Lösung
Den Wert über «Neuen Wert setzen …» eingeben und erneut speichern.
«Der Header … sieht wie ein Secret aus»
Problem
Ein statischer Header oder eine Property trägt einen Namen, der auf Zugangsdaten hinweist.
Lösung
Den Wert nicht als Header oder Property erfassen, sondern den passenden Auth-Typ wählen und den Wert dort setzen.
«Speichern fehlgeschlagen. Die Schnittstelle wurde durch einen anderen Benutzer modifiziert.»
Problem
Jemand hat die Schnittstelle geändert, während Sie sie geöffnet hatten.
Lösung
Die Schnittstelle neu öffnen und die Änderung wiederholen.
«Deaktivieren Sie die Schnittstelle vor dem Löschen.»
Problem
Eine aktive Schnittstelle lässt sich nicht löschen.
Lösung
Die Schnittstelle öffnen, «Deaktivieren» wählen und danach löschen.
Eine Transaktion bricht ab: «differ from the definition of service»
Problem
Die Transaktion setzt scope, tokenAuthMethod oder apiKeyHeader mit einem anderen Wert als die Schnittstelle.
Lösung
Die Eigenschaft aus der Transaktion entfernen und den Wert in der Schnittstelle setzen.
Der Aufruf schlägt fehl, obwohl die Diagnose alles als lesbar zeigt
Problem
Die Diagnose prüft nicht, ob das Drittsystem die Zugangsdaten annimmt.
Lösung
Die Zugangsdaten beim Anbieter prüfen und neu setzen. Bei einem Client-Zertifikat das Ablaufdatum in der Liste «Keystores» kontrollieren.
...
- Elf Screenshots aufnehmen und mit den vorgegebenen Dateinamen anhängen
- Beschriftung des Knopfs für eine neue Schnittstelle und einen neuen Keystore in der Oberfläche prüfen und im Text ergänzen
- Prüfen, ob die Felder «Name» und «Beschreibung» einer Transaktion in der Oberfläche als Pflicht gelten
- Diesen Abschnitt vor der Veröffentlichung entfernen