B2B Exchange betreiben

Mit B2B Exchange verarbeiten Sie EDIFACT-Bestellungen eines Handelspartners in Workspace und stellen die Bestellantwort wieder für diesen Partner bereit. Dieser Betriebsvertrag hat keine Administrationsoberfläche. Richten Sie ihn über die autorisierten Server-APIs ein und verwenden Sie dafür bei Bedarf nucli als tenantgebundenen HTTP-Client.

Der aktuelle Funktionsumfang ist bewusst eng:

Lesen Sie EDI/EDIFACT verstehen und einführen, wenn Sie Standard, Verzeichnis und Partnerprofil zuerst einordnen müssen. Für ein neues Partner-Onboarding führt Sie EDIFACT-Partner einrichten in einer kompakten Abnahmereihenfolge durch diesen ausführlichen Betriebsvertrag.

Verarbeitungsweg verstehen

Workspace trennt dabei Transport-, Syntax-, Mapping-, Anwendungs- und Bestätigungsstatus. Ein erfolgreicher Upload bedeutet deshalb noch nicht, dass die Bestellung fachlich angewendet oder die Antwort ausgeliefert wurde.

Berechtigungen vorbereiten

Geben Sie Administratoren nur die benötigten Aktionen auf diesen Berechtigungsfamilien:

• b2b_exchange_partners
• b2b_exchange_identifiers
• b2b_exchange_connections
• b2b_exchange_commerce_bindings
• b2b_exchange_profiles, einschließlich activate
• b2b_exchange_messages für Liste, Lesen, Review, Retry, Cancel und Payload-Zugriff

Die jeweilige Aktion steht hinter dem Doppelpunkt, etwa b2b_exchange_connections:create. Prüfen Sie den aktiven Mandanten und die Scopes vor einer Änderung:

nucli --tenant <tenant> whoami
nucli --tenant <tenant> scopes
nucli --tenant <tenant> api GET /api/v1/b2b-exchange/partners --summary

Lesen Sie nucli, wenn Sie Profile, Tenant-Guard oder nucli api zuerst einrichten müssen. Mutierende Aufrufe erhalten ihren JSON-Body über --input <datei> oder --input -.

Konfiguration in stabiler Reihenfolge anlegen

Legen Sie Partner und Commerce-Bindung zunächst inaktiv sowie Verbindungen und Profile als Entwurf an. Führen Sie keine Live- oder Transporttests gegen diese Zustände aus. Aktivieren Sie erst den vollständigen Vertrag und beginnen Sie danach mit Test und Abnahme.

Eine aktivierte Revision bleibt unveränderlich. Erstellen und aktivieren Sie eine neue Revision, wenn sich Mapping oder Bestätigungsrichtlinie ändern. Nutzen Sie für ORDERS die Richtung inbound und für ORDRSP die Richtung outbound. Der aktuelle W2-Vertrag unterstützt automatic, review_on_difference und manual als Anwendungsrichtlinien.

Fixture-Nachweise verifizieren

Legen Sie für jede Revision mindestens einen Fixture-Nachweis unter /api/v1/b2b-exchange/profiles/{profileID}/revisions/{revisionID}/fixtures/ an. Verweisen Sie dabei auf bereits autorisierte, mandantengebundene Storage-Objekte und geben Sie deren SHA-256-Hashes an. Der Fixture-Endpunkt nimmt keine Nutzdaten entgegen und gibt keine Nutzdaten zurück.

• Für ein eingehendes ORDERS enthält inputStorageObjectId EDIFACT und expectedStorageObjectId die erwartete kanonische JSON-Bestellung.
• Für ein ausgehendes ORDRSP enthält inputStorageObjectId die kanonische JSON-Antwort und expectedStorageObjectId das erwartete EDIFACT-Dokument.
• Für expectedOutcome: "valid" müssen Sie das Expected-Objekt und seinen Hash angeben. Lassen Sie expectedErrorCode leer.
• Für expectedOutcome: "rejected" dürfen Sie kein Expected-Objekt angeben. Verwenden Sie als expectedErrorCode ausschließlich ERR_B2B_EXCHANGE_FIXTURE_SYNTAX oder ERR_B2B_EXCHANGE_FIXTURE_MAPPING.

Ein neuer Nachweis hat verificationStatus: "pending". Starten Sie die deterministische Prüfung mit POST .../fixtures/{fixtureID}/verify. Das Ergebnis ist terminal:

• succeeded ohne observedErrorCode bestätigt einen gültigen Fixture-Fall.
• succeeded mit einem observedErrorCode, der dem erwarteten Code entspricht, bestätigt einen erwarteten Ablehnungsfall.
• failed hält den tatsächlich beobachteten stabilen Fehlercode und verifiedAt dauerhaft fest. Löschen Sie den Nachweis und legen Sie ihn nach der Korrektur neu an; eine erneute Prüfung desselben Nachweises ist nicht zulässig.

Die Aktivierung sperrt, solange ein Nachweis fehlt, nicht erfolgreich geprüft ist oder Erwartung und beobachtetes Ergebnis voneinander abweichen. Nach der Aktivierung können Sie die Revision und ihre Fixture-Nachweise weder ändern noch löschen. Die Fixture-Prüfung belegt nur den Mapping-Vertrag; führen Sie die Transport- und Live-Abnahme anschließend getrennt aus.

Eindeutigkeit vor der Aktivierung prüfen

Für jeden aktiven Partner muss der laufende Vertrag genau diese Kardinalität haben:

Eine zweite aktive Profilzuordnung bleibt unzulässig. Mehrere API-Verbindungen und mehrere SFTP-Eingangsverbindungen mit unterschiedlichen Tupeln sind dagegen gültig. Mehrdeutig wird der Transportvertrag erst durch ein doppeltes aktives SFTP-Eingangstupel oder mehr als einen aktiven SFTP-Ausgang desselben Partners.

API-Verbindung konfigurieren

Eine Partner-API-Verbindung verwendet diese festen Werte:

Ein Partner darf mehrere aktive API-Verbindungen besitzen. Jeder Aufruf adressiert eine konkrete Connection-ID; genau diese Verbindung bindet sowohl deren Inbox als auch deren ausgehende Mailbox.

Die API-Verbindung akzeptiert keine Credential-, Signing- oder Encryption-Secret-ID. Erstellen Sie stattdessen für die gebundene Partner-Identity einen tenantfesten API-Key mit genau den benötigten Partner-Scopes. Der technische Abrufvertrag steht in B2B-Exchange-Partner-API integrieren.

SFTP-Eingang konfigurieren

Der SFTP-Eingang nutzt den bestehenden storagegebundenen SFTP-Listener. Die Verbindung ordnet einen erfolgreichen Upload eindeutig über Identity und Store zu:

Aktivieren Sie für jedes Tupel (Tenant, PartnerIdentityID, InboundStoreID) genau eine SFTP-Eingangsverbindung. Mehrere aktive Eingangsverbindungen mit unterschiedlichen Tupeln sind zulässig.

Bereiten Sie den Storage-Zugang vollständig vor:

1. Legen Sie einen tenantgebundenen Store an und aktivieren Sie darin die SFTP-Einstellung sftp.enabled.
2. Geben Sie der in partnerIdentityId gebundenen Identity eine Editor-ACL auf der Ressource StorageStore für genau diesen Store.
3. Erstellen Sie für dieselbe Identity einen aktiven API-Key mit festem Mandanten. Seine angeforderten Scopes und die effektiven Rollen-Scopes müssen jeweils storage_object:create enthalten.
4. Tragen Sie denselben Store in inboundStoreId ein und aktivieren Sie für diese Identity-/Store-Zuordnung genau eine SFTP-Eingangsverbindung.

Der SFTP-Listener verwendet diese kanonischen Anmeldedaten:

Andere Identity-, Mandanten-, Store- oder Scope-Kombinationen werden nicht auf eine B2B-Verbindung aufgelöst. Andere SSH-Anmeldearten gehören nicht zu diesem Eingangsvertrag. Lesen Sie Dokumente und Storage für die Store-Verwaltung. Die vorstehende Username-/Passwort-Regel ist der kanonische SFTP-Anmeldevertrag für B2B Exchange.

SFTP-Ausgang absichern

Der SFTP-Ausgang verwendet transport: "sftp" und adapterKey: "sftp.outbound.v1". Halten Sie nur öffentliche Verbindungsmetadaten in configuration:

{
  "host": "sftp.partner.example",
  "port": 22,
  "remoteDirectory": "/outbound/orders",
  "hostKeySHA256": "SHA256:<geprüfter-fingerprint>",
  "connectTimeoutSeconds": 10,
  "operationTimeoutSeconds": 45
}

Dabei gelten diese Grenzen:

• port ist fest auf 22 begrenzt.
• hostKeySHA256 ist Pflicht. Übernehmen Sie den SHA-256-Fingerprint über einen getrennten, vertrauenswürdigen Kanal.
• connectTimeoutSeconds darf höchstens 30, operationTimeoutSeconds höchstens 120 betragen.
• remoteDirectory ist ein absoluter, normalisierter Zielpfad ohne Traversal-Segmente.
• Der Zielserver muss die SFTP-Erweiterung posix-rename@openssh.com bereitstellen. Fehlt sie, schlägt die Auslieferung fehl.
• Der Adapter schreibt zunächst exklusiv in eine temporäre Datei, veröffentlicht sie ausschließlich über posix-rename@openssh.com und prüft danach Größe und SHA-256-Hash am Ziel.

credentialSecretId muss auf ein geschlossenes JSON-Objekt im tenantgebundenen Secret Store verweisen. Es sind ausschließlich diese beiden Formen zulässig:

Weitere Felder oder nach dem JSON-Objekt angehängte Daten führen zum Fehler. Das vollständige JSON darf höchstens 256 KiB groß sein. username ist Pflicht, umfasst 1 bis 128 UTF-8-Bytes und darf keine führenden oder nachgestellten Leerzeichen, Nullbytes oder Zeilenumbrüche enthalten. Beim Typ password ist das gleichnamige Feld Pflicht, nicht leer und höchstens 4096 UTF-8-Bytes lang. Beim Typ private_key muss privateKey nicht leeres SSH-Schlüsselmaterial enthalten. Legen Sie weder Benutzername noch Passwort, SSH-Schlüsselmaterial oder Passphrase in configuration, Logs, Tickets oder nucli-Kommandozeilen ab.

Private Zielnetze sind standardmäßig blockiert. Nur ein Betreiber mit globaler Konfigurationsberechtigung kann einzelne private CIDR-Bereiche über den gesperrten Konfigurationsschlüssel b2b_exchange.sftp.outbound.allowed_private_cidrs freigeben. Ein Mandant oder eine Verbindung kann diese Allowlist nicht erweitern. Spezielle Zieladressen und gemischte öffentliche/private DNS-Antworten bleiben blockiert; der Adapter pinnt außerdem die geprüfte Zieladresse für den Verbindungsaufbau.

Nachrichten überwachen und bearbeiten

Nutzen Sie die Nachrichten-API für den operativen Verlauf:

nucli --tenant <tenant> api GET '/api/v1/b2b-exchange/messages?limit=50' --summary
nucli --tenant <tenant> api GET /api/v1/b2b-exchange/messages/<interchange-id> --summary

Prüfen Sie die Statusachsen einzeln:

Verwenden Sie die Aktionen gezielt:

• POST /api/v1/b2b-exchange/messages/{interchangeID}/retry stößt einen neuen kontrollierten Versuch für einen fehlgeschlagenen Vorgang an.
• POST /api/v1/b2b-exchange/messages/{interchangeID}/cancel beendet einen noch abbrechbaren Vorgang.
• POST /api/v1/b2b-exchange/messages/{interchangeID}/review bestätigt oder verwirft eine Nachricht, die fachliche Prüfung verlangt. Senden Sie dabei die zugehörige messageId, approve ohne Reason-Code oder reject mit stabilem Reason-Code.
• GET /api/v1/b2b-exchange/messages/{interchangeID}/payload liest die Nutzlast nur mit dem gesonderten Payload-Read-Scope und erzeugt Auditdaten.

Wiederholen Sie nicht blind. Prüfen Sie zuerst Fehlercode, Statusachsen, Profilrevision, Partnerbindung und Zielverbindung. Ein Retry behält die fachliche Identität des Vorgangs und ist kein Ersatz für eine korrigierte Konfiguration.

Fehler sicher diagnostizieren

Die API liefert stabile ERR_B2B_EXCHANGE_*-Codes und absichtlich keine rohen SQL-, Storage-, Netzwerk- oder Kryptofehler. Behandeln Sie diese Reduktion als Sicherheitsvertrag.

Übernehmen Sie niemals einen Rohfehler in eine Partnerantwort. Geben Sie nur den stabilen Code, eine eigene Korrelation und den nächsten sicheren Schritt weiter.

Betrieb abnehmen

Der Vertrag ist betriebsbereit, wenn:

• Partner, Identifier, exakt zugeordnete Verbindungen, Commerce-Bindung sowie die aktiven ORDERS- und ORDRSP-Profilrevisionen im richtigen Mandanten liegen,
• ein Testinterchange für jede aktivierte Verzeichnis- und Syntaxkonfiguration erst nach vollständiger Aktivierung den erwarteten Status durchläuft,
• Duplikate keine zweite Commerce-Bestellung und keine zweite fachliche ORDRSP erzeugen,
• CONTRL und APERAK gemäß Bestätigungsrichtlinie erscheinen,
• die Partner-API Nutzlasten vollständig mit Größe, Hash und Abschlussstatus prüft oder der SFTP-Ausgang die atomar veröffentlichte Datei bestätigt,
• unberechtigte Zugriffe keine fremden Partner-, Verbindungs- oder Payload-Informationen offenlegen.

Entwickler finden Mapping-, Fixture- und Testkonventionen unter Als Entwickler mit EDIFACT arbeiten sowie den vollständigen Partner-API-Vertrag unter B2B-Exchange-Partner-API integrieren.