Schnittstellenprovider konfigurieren, testen und überwachen

Zweck und Einsatzbereich

Unter Einstellungen → Schnittstellen verwalten Organisationsadministratoren die mandantenbezogenen Provider-Blueprints. Der geprüfte Katalog enthält 24 Vorlagen aus den Bereichen Häfen, Zoll, Reedereien, Finanzbuchhaltung, Bonität, Compliance, Tarife und Luftfracht. Dazu gehören unter anderem DAKOSY, dbh, Portbase, NxtPort, ATLAS, INTTRA und direkte Carrier-Vorlagen.

Eine Vorlage ist noch keine produktive Anbindung. Katalogname, vorgeschlagene Zieladresse, Authentifizierungsart und Mapping-Bezeichnung belegen weder einen Providervertrag noch eine Zertifizierung, Freischaltung oder fachliche Verarbeitung. Vor Livebetrieb müssen Provider, aktuelle technische Spezifikation, Nachrichtenprofil, Testzugang, Datenschutz, Supportweg und Abnahme schriftlich bestätigt sein.

Die Workbench unterscheidet Deaktiviert, Blueprint, Simulation, Fehler und Live bereit. Im Simulationsmodus werden bei einem Verbindungstest keine externen Systeme angesprochen; ein Erfolg mit null Millisekunden ist daher nur eine Simulation und kein Erreichbarkeitsnachweis. Ein echter Verbindungstest findet erst im Live-Modus statt. Auch ein erfolgreicher echter Test bestätigt lediglich den technischen Antwortstatus des Testziels, nicht das Nachrichtenmapping oder die fachliche Annahme.

Voraussetzungen und Berechtigungen

Die Konfigurationsseite ist für ADMIN und in der Navigation auch für Plattformadministratoren vorgesehen. Lesen, Ändern, Umschalten und Testen sind serverseitig auf diese Administratorrolle begrenzt.
Zusätzlich muss in der aktiven Organisationseinheit mindestens eines der Module Ocean Export, Ocean Import, Compliance oder Finance zugelassen sein. Der gemeinsame Schnittstellenbereich ist nicht nach dem konkreten Providerfachgebiet getrennt. Ein nur für Luftfracht lizenzierter Mandant kann deshalb die dort vorhandenen Luftfrachtvorlagen derzeit nicht über diesen Bereich verwalten.
Die Providerkonfiguration gilt für den gesamten Mandanten. Sie besitzt keine eigene Organisationseinheit; ein Wechsel der Einheit erzeugt keine getrennte Konfiguration. Die aktive Einheit beeinflusst jedoch den Lizenzzugriff auf die Seite.
Plattformadministratoren arbeiten technisch mit globalen Konfigurationen ohne Mandantenzuordnung. In strikt durchgesetzter Lizenzierung fehlt ihnen für diesen Bereich derzeit der erforderliche Mandantenkontext; dann kann die sichtbare Seite trotz Plattformrolle abgewiesen werden. Mandantenspezifische Freigaben müssen bis zur Korrektur durch den jeweiligen Organisationsadministrator erfolgen.
API-Schlüssel und Passwörter werden verschlüsselt gespeichert und nicht im Klartext zurückgegeben. Zertifikate müssen zuvor durch den Plattformbetrieb in einem dafür freigegebenen Serverbereich abgelegt werden; der Dialog lädt keine Zertifikatsdatei hoch.
Für eine produktive Abnahme benötigen Sie ein isoliertes Provider-Testsystem, synthetische Testfälle, erwartete Positiv- und Negativantworten, eine Rückfallentscheidung und einen verantwortlichen Ansprechpartner beim Provider. Verwenden Sie nie echte Zugangsdaten in Screenshots, Tickets oder Handbuchbeispielen.

Die separate Ansicht Werkzeuge → Schnittstellen-Status ist für weitere interne Rollen sichtbar. Die dortige Schaltfläche Testen erfordert technisch dennoch Administratorrechte. Nichtadministratoren können den Status lesen, aber den Test im aktuellen Stand nicht erfolgreich auslösen.

Schritt-für-Schritt-Anleitung

Provider und Testumfang festlegen

Dokumentieren Sie Zielprozess, Provider, Mandant, benötigte Organisationseinheiten, Test- und Produktivumgebung sowie verantwortliche Personen.
Lassen Sie sich die aktuelle Zieladresse, Authentisierung, erforderlichen Kennungen, Nachrichtenprofile, Callback-Verfahren und fachlichen Antwortcodes direkt vom Provider bestätigen. Übernehmen Sie keine Katalogwerte ungeprüft.
Definieren Sie mindestens einen positiven Test, einen Authentisierungsfehler, einen fachlichen Ablehnungsfall, einen Timeoutfall und einen Dublettenfall. Ein bloßer Erreichbarkeitstest genügt nicht.
Öffnen Sie Einstellungen → Schnittstellen, suchen Sie den Provider und prüfen Sie Kategorie, Aktivstatus und Modus. Beginnen Sie immer mit Simulation.

Konfiguration im Simulationsmodus vorbereiten

Wählen Sie Konfigurieren. Tragen Sie in API-URL ausschließlich das Ziel ein, das die Anwendung tatsächlich verwenden soll. Die getrennten Felder Sandbox-URL und Live-URL schalten den Transport im geprüften Stand nicht um.
Wählen Sie die vereinbarte Authentisierungsart. Tragen Sie API-Schlüssel oder Client-Secret nur im verdeckten Geheimnisfeld ein. Bei einem Clientzertifikat muss der Plattformbetrieb zuerst die Datei bereitstellen und den freigegebenen Zertifikatspfad mitteilen.
Pflegen Sie nur bestätigte Sender-, EORI- oder Mandantenkennungen. Hinterlegen Sie ein Mapping-Profil erst nach fachlicher Freigabe; die sichtbare Bezeichnung allein aktiviert keine Feldtransformation.
Lassen Sie Schnittstelle aktiv schalten zunächst deaktiviert und wählen Sie Simulationsmodus. Speichern Sie die Konfiguration.
Öffnen Sie die Karte erneut und kontrollieren Sie, dass URL, Modus und Aktivstatus plausibel erscheinen. Verlassen Sie sich derzeit nicht auf die sichtbare Anzeige Zugangsdaten vorhanden oder auf wieder eingeblendete Detailwerte; lassen Sie die gespeicherte Geheimnis- und Zertifikatskonfiguration durch den berechtigten Betrieb gegenprüfen.
Wählen Sie Test nur zur Kontrolle des Simulationspfads. Ein grüner Hinweis im Simulationsmodus bedeutet ausdrücklich kein echter Verbindungstest.

Echten Verbindungstest und Livefreigabe durchführen

Sperren Sie während der Abnahme alle operativen Provideraktionen für normale Benutzer. Ein Live-Modus kann echte Geschäftsdaten versenden, sobald eine Fachaktion ausgelöst wird.
Verwenden Sie in API-URL zunächst die vertraglich bestätigte Testumgebung. Speichern Sie Änderungen im Simulationsmodus, bevor Sie Verbindung testen verwenden; die Testschaltfläche im geöffneten Dialog prüft sonst die zuletzt gespeicherte Konfiguration, nicht zwingend die gerade eingegebenen Werte.
Wählen Sie Live-Modus und bestätigen Sie die Freigabe. Der Server prüft Pflichtfelder und führt vor der Umschaltung einen echten technischen Test aus. Bei einem Fehler muss der Simulationsmodus bestehen bleiben.
Prüfen Sie nach erfolgreicher Umschaltung Zeitpunkt, Latenz und Ergebnis. Führen Sie anschließend die vereinbarten fachlichen Testmeldungen über den jeweiligen Arbeitsprozess aus und gleichen Sie Providerquittungen sowie Nachrichtenprotokoll ab. Verwenden Sie dazu die Anleitung Carrier-, Hafen- und Zollmeldungen mit Providern übermitteln.
Schalten Sie nach der Testabnahme zurück auf Simulation, solange noch kein Produktivfenster freigegeben ist.
Für den Produktivstart ersetzen Sie API-URL kontrolliert durch das bestätigte Produktivziel, prüfen die Zugangsdaten erneut und wiederholen technischen sowie fachlichen Test. Das ausgefüllte Feld Live-URL übernimmt diese Umschaltung derzeit nicht automatisch.
Dokumentieren Sie Freigabezeitpunkt, verantwortliche Personen, Providerbeleg und Rückfallplan. Aktivieren Sie Live erst, wenn fachliches Mapping, Berechtigungen, Monitoring und Fehlerbehandlung abgenommen sind.

Status kontrollieren

Prüfen Sie in der Workbench täglich den tatsächlichen Modus, den letzten Testzeitpunkt und ein vorhandenes Fehlerergebnis. Die Werte stammen aus gespeicherter Konfiguration und manuell ausgelösten Tests; ein regelmäßiger tenantbezogener Uptime-Test ist im geprüften Stand nicht belegt.
Öffnen Sie ergänzend Werkzeuge → Schnittstellen-Status. Bewerten Sie die Statuszeilen und den letzten Test, nicht den gelben Pauschalhinweis: Dieser behauptet derzeit unabhängig von den Daten, alle Schnittstellen seien in Simulation.
Bei Fehler stoppen Sie den betroffenen Fachprozess, wechseln kontrolliert auf Simulation oder deaktivieren den Anschluss und klären Provider, Netzwerk, Zertifikat und Zugangsdaten. Ein gespeicherter Retry-Wert führt im gemeinsamen Transport derzeit nicht zu automatischen Wiederholungen.
Nach jeder Änderung führen Sie erneut technischen Test, fachlichen Test und Protokollabgleich durch. Ein grünes Aktiv oder Live bereit ist kein Nachweis einer fortlaufenden Verfügbarkeit.

Feldreferenz

Feld	Pflicht	Bedeutung	Validierung
API-URL	Ja für Live	Tatsächlich verwendetes Basisziel für Test und Versand	Nur aktuelle, vertraglich bestätigte HTTPS-Ziele verwenden. Interne oder unsichere Netzwerkziele werden geprüft; der sichtbare Katalogwert ist keine Providerbestätigung.
Port	Anbieterabhängig	Optionaler Netzwerkport	Der gespeicherte Port wird vom gemeinsamen HTTP-Transport nicht separat an die URL angefügt. Falls nötig, muss der bestätigte Port Bestandteil der API-URL sein.
Sandbox-URL	Nein	Dokumentationsfeld für ein mögliches Provider-Testziel	Wird gespeichert, wählt aber den aktiven Transport im geprüften Stand nicht aus. Für einen echten Test muss das Testziel in API-URL stehen.
Live-URL	Nein	Dokumentationsfeld für ein mögliches Produktivziel	Wird gespeichert, aber beim Umschalten auf Live nicht automatisch verwendet. Produktivziel kontrolliert in API-URL übernehmen.
Methode	Ja	Angezeigte Authentisierungsart: API-Key, Zertifikat oder OAuth	Muss zum Providervertrag passen. Der gemeinsame Transport unterstützt Bearer-Schlüssel, Benutzername/Passwort und Clientzertifikat; ein vollständiger OAuth-Tokenaustausch ist im geprüften generischen Weg nicht belegt.
API-Key	Bedingt	Geheimer Bearer-Schlüssel	Verdeckt eingeben, verschlüsselt speichern und niemals dokumentieren. Ein leeres Feld soll einen vorhandenen Schlüssel unverändert lassen; den gespeicherten Zustand derzeit zusätzlich betrieblich prüfen.
Zertifikat-Pfad	Bedingt	Serverpfad eines vom Betrieb installierten Clientzertifikats	Muss in dem freigegebenen Zertifikatsbereich liegen und auf eine vorhandene Datei zeigen. Der Dialog ist kein Datei-Upload.
Username / EORI	Bedingt	Teilnehmer-, Benutzer- oder EORI-Kennung	Format und Mandantenzuordnung gegen Providerunterlagen prüfen; keine allgemeine fachliche Formatprüfung belegt.
Passphrase / Client-Secret	Bedingt	Geheimes Passwort zum Zertifikat oder zur Clientkennung	Verdeckt eingeben und nur über einen freigegebenen Secret-Kanal beschaffen. Wird verschlüsselt gespeichert.
Mapping-Profil	Anbieterabhängig	Bezeichnung eines providerbezogenen Feldmappings	Der Name wird gespeichert und kann als Pflichtfeld gelten; eine generische Laufzeittransformation anhand dieses Feldes ist nicht belegt. Fachlich abgenommenes Mapping separat nachweisen.
Kontakt E-Mail	Nein	Interne Setup- oder Eskalationsnotiz	Keine automatische Benachrichtigung aus diesem Feld belegt. Nur Funktionsadresse ohne Geheimnisse verwenden.
Sender-ID / EORI	Anbieterabhängig	Zusätzliche Absenderkennung für ausgehende Nachrichten	Kann als Header übertragen werden. Exakte Kennung und Berechtigung durch Provider bestätigen lassen.
Sync (Min)	Nein	Vorgesehener Synchronisationsabstand	Wird gespeichert; ein dazugehöriger Scheduler ist für diese Workbench nicht belegt. Nicht als aktiven Abrufplan behandeln.
Timeout (Sek)	Ja für kontrollierten Test	Maximale Wartezeit für Test und gemeinsamen Versand	Nur positive, begrenzte Zahlen verwenden. Die Oberfläche und der Server begrenzen oder validieren den Wert derzeit nicht ausreichend.
Retries	Nein	Vorgesehene Zahl erneuter Versuche	Wird gespeichert, aber im gemeinsamen Verbindungstest und Transport nicht ausgeführt. Wiederholungen nicht voraussetzen.
Webhook / Callback	Anbieterabhängig	Vorgesehene Rückrufadresse für Providerereignisse	Das Feld registriert oder validiert keinen generischen Callback. Nur verwenden, wenn ein separat belegter, authentisierter Empfangsweg abgenommen ist.
Schnittstelle aktiv schalten	Ja für Nutzung	Aktiviert die Konfiguration für operative Providerpfade	Zunächst deaktiviert lassen. Aktiv allein bedeutet weder erreichbar noch live.
Simulationsmodus	Ja	Trennt simulierte Antworten von echten externen Aufrufen	Simulation spricht beim Verbindungstest kein externes Ziel an. Live erfordert Pflichtfelder und einen erfolgreichen technischen Test.

Providerabhängige Nachrichtenpfade und zertifizierte Nachrichtenprofile sind im sichtbaren Dialog nicht vollständig pflegbar. Muss der Provider solche Werte verlangen, ist eine technische Betriebskonfiguration und eine separate fachliche Abnahme erforderlich; erfinden Sie keine Pfade oder Profile aus Katalognamen.

Status und mögliche Übergänge

Ausgangszustand	Aktion oder Ereignis	Ergebnis
Vorlage neu angelegt	Katalog wird für den Mandanten geladen	Fehlende Vorlagen werden angelegt; Provider aus Hafen, Zoll und Reederei starten aktiv, aber im Simulationsmodus, andere Vorlagen können deaktiviert starten. Bestehende Betreiberwerte sollen erhalten bleiben.
Deaktiviert	Konfiguration vorbereiten und speichern	Werte sind hinterlegt, operative Nutzung bleibt gesperrt.
Aktiv und Simulation	Test ausführen	Sofortiger Simulationserfolg ohne externen Netzwerkzugriff; Zeitpunkt und Ergebnis werden gespeichert.
Simulation mit fehlenden Pflichtfeldern	Auf Live umschalten	Umschaltung wird abgewiesen; Simulation soll aktiv bleiben.
Simulation mit vollständigen Pflichtfeldern	Auf Live umschalten	Echte technische Prüfung; nur bei Erfolg wird Live gespeichert.
Live und letzter Test fehlgeschlagen	Status neu laden	Fehler; operativen Versand stoppen und Ursache klären.
Live, aktiv und Pflichtfelder vollständig	Status neu laden	Kann als Aktiv oder Live bereit erscheinen. Die Statuslogik verlangt nicht in jedem Fall einen frischen erfolgreichen Test; Zeitstempel und Providerbeleg separat prüfen.
Live	Simulationsschalter aktivieren	Künftige gemeinsame Provideraktionen wechseln in Simulation, sofern die Umgebung Simulation erlaubt. Bereits extern versendete Meldungen werden nicht zurückgenommen.
Beliebiger Zustand	Schnittstelle deaktivieren	Operative Liveübertragung wird gesperrt; Konfiguration und letzter Test bleiben gespeichert.

Ein Statuswechsel ersetzt keine fachliche Quittung. Aktiv, ein grüner technischer Test und eine geringe Latenz sagen nicht aus, ob Booking, Hafenmeldung, Zollnachricht oder Finanzdatensatz vom Provider fachlich akzeptiert wurde.

Was im Hintergrund passiert

Konfigurationen werden nach Mandant getrennt gespeichert und zusätzlich durch Datenbankrichtlinien auf diesen Mandanten begrenzt. Sie sind nicht nach Organisationseinheit getrennt. Plattformweite Einträge ohne Mandant bleiben von den Konfigurationen einzelner Kunden getrennt und werden nicht automatisch als Mandantenanschluss verwendet.

API-Schlüssel und Passwörter werden verschlüsselt abgelegt. Listen liefern keine Klartextgeheimnisse. Clientzertifikate bleiben als vom Plattformbetrieb verwaltete Dateien auf dem Server; die Anwendung akzeptiert nur Pfade aus dem vorgesehenen Zertifikatsbereich. Ausgehende Ziele werden vor einem echten Aufruf gegen unzulässige Netzwerkziele geprüft und TLS-Zertifikate werden verifiziert.

Im Simulationsmodus gibt der Verbindungstest absichtlich sofort Erfolg zurück. Im Live-Modus führt er einen lesenden technischen Aufruf an einem je Providertyp hinterlegten Prüfpfad aus. Beim Umschalten auf Live prüft der Server zuerst die im Katalog genannten Pflichtfelder und verweigert die Umschaltung bei einem fehlgeschlagenen Test. Der spätere operative Versand verwendet hingegen einen separaten, providerabhängigen Nachrichtenpfad und kann fachlich anders reagieren.

Der Katalog wird beim Laden ergänzt, ohne bestehende Zieladresse, Authentisierungsart, Aktivstatus oder Geheimnisse bewusst zu überschreiben. Mehrere Metadaten der Workbench – insbesondere Mappingname, Sandbox-/Live-URL, Sync-Intervall, Retryzahl, Kontakt und generischer Callback – sind im geprüften Stand überwiegend Vorbereitungs- oder Dokumentationswerte. Sie dürfen erst dann als wirksam gelten, wenn der konkrete Providerweg und sein automatisierter Test dies belegen.

Aktenbezogene Nachrichtenprotokolle werden über die jeweilige Akte auf Mandant und Organisationseinheit begrenzt. ADMIN und MANAGER können innerhalb ihres Mandanten alle Einheiten erreichen; andere Rollen nur zugewiesene Einheiten. Plattformadministratoren dürfen das organisationsweite Nachrichtenprotokoll nicht einsehen. Die Workbench selbst zeigt derzeit keine vollständige Nachrichtenhistorie; diese gehört in den jeweiligen Fachprozess.

Automatisierte Tests belegen, dass Katalogaktualisierungen vorhandene Livewerte nicht überschreiben sollen, globale und mandantenbezogene Konfigurationen nicht vermischt werden, fehlende Pflichtzugänge Live verhindern, eine fehlerhafte Livekonfiguration nicht auf Simulation zurückfällt und Zertifikatspfade begrenzt sind. Nicht belegt sind vollständige UI-End-to-End-Tests, OAuth-Tokenfluss, Retry/Scheduler/Callback-Wirkung, Providerzertifizierung sowie eine periodische tenantbezogene Gesundheitsprüfung.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
Fehler beim Laden der Schnittstellen-Konfiguration	Rolle, Lizenz der aktiven Einheit, Mandantenkontext oder Serververbindung fehlt.	Aktive Organisationseinheit, mindestens eines der vier zulässigen Module und Administratorrolle prüfen. Plattformadministratoren benötigen derzeit gegebenenfalls einen Mandantenadministrator.
Keine Schnittstellen für die aktuelle Auswahl gefunden	Suchbegriff, Kategorie oder Statusfilter schließt alle Karten aus.	Filter auf Alle zurücksetzen und nur nach dem Provider-Kürzel suchen.
Verbindung erfolgreich mit 0 ms	Test wurde im Simulationsmodus ausgeführt.	Nicht als Providererreichbarkeit werten. Für einen echten Test kontrolliertes Provider-Testziel in API-URL setzen und den abgesicherten Livefreigabeablauf verwenden.
Test im Dialog berücksichtigt neue Eingaben nicht	Verbindung testen prüft die zuletzt gespeicherte Konfiguration.	Änderungen zunächst im Simulationsmodus speichern, danach kontrolliert testen.
Fehlende Pflichtkonfiguration	Mindestens ein katalogseitig erforderliches Feld fehlt.	Nur die vom Provider bestätigten Pflichtwerte ergänzen; Zertifikat durch den Plattformbetrieb bereitstellen lassen.
Keine API-URL konfiguriert	Tatsächliches Basisziel fehlt; Sandbox- oder Live-URL allein genügt nicht.	Bestätigtes Test- oder Produktivziel in API-URL eintragen.
Verbindung abgelehnt, Timeout oder technischer Fehler	Ziel nicht erreichbar, falscher Prüfpfad, Firewall, Zertifikat, Authentisierung oder ungeeigneter Timeout.	Auf Simulation zurückschalten, Provider- und Betriebsdaten abgleichen und erst nach kontrolliertem Test erneut freigeben.
OAuth-Verbindung bleibt erfolglos	Der generische Transport besitzt keinen belegten vollständigen OAuth-Tokenaustausch.	Nicht durch wiederholtes Speichern umgehen. Providerbezogene OAuth-Implementierung und Testnachweis durch den technischen Betrieb verlangen.
Karte zeigt fehlende Zugangsdaten trotz bereits gespeicherten Secrets	Die aktuelle Konfigurationsantwort liefert nicht alle von der Workbench erwarteten Secret-Statusfelder.	Nicht vorschnell neue Secrets eintragen oder live schalten; gespeicherten Zustand betrieblich prüfen lassen.
Gespeicherter Port, Zertifikatspfad oder Betriebsdetail erscheint beim erneuten Öffnen leer	Nicht alle gespeicherten Felder werden an die Oberfläche zurückgegeben. Erneutes Speichern kann einzelne Betriebsnotizen mit Leer- oder Standardwerten überschreiben.	Dialog abbrechen und Konfiguration durch den berechtigten Betrieb prüfen lassen; nicht blind neu speichern.
Schnittstellen-Status behauptet pauschal, alle Anschlüsse seien Simulation	Der gelbe Hinweis ist statisch und nicht aus den Statusdaten berechnet.	Modus und Testzeitpunkt in jeder Statuszeile sowie in der Administrator-Workbench prüfen.
Nichtadministrator kann Testen sehen, erhält aber einen Fehler	Die Statusseite zeigt die Aktion breiter an, der Server erlaubt sie nur Administratoren.	Test durch einen Organisationsadministrator ausführen lassen.
Luftfrachtprovider fehlen im Status oder sind für Air-only-Mandanten nicht erreichbar	Die Statusoberfläche rendert die Luftfrachtgruppe nicht; der gemeinsame Lizenzschutz umfasst nur Ocean, Compliance und Finance.	Luftfrachtanschluss nicht anhand dieser Ansicht freigeben; Plattformbetrieb und Luftfracht-Fachtest einbeziehen.
Automatische Wiederholung, Synchronisation oder Callback bleibt aus	Retry-, Sync- und Webhookfelder sind im gemeinsamen Weg noch nicht als laufende Automatik belegt.	Keine Wirkung voraussetzen; konkreten Scheduler, Retry-Mechanismus oder authentisierten Callback separat implementieren und abnehmen lassen.