B2B-Exchange-Partner-API integrieren

Über die Partner-API senden Sie EDIFACT-ORDERS an eine fest gebundene Verbindung und holen ausgehende ORDRSP-, CONTRL- oder APERAK-Nachrichten aus deren Mailbox ab. Die Versionszuordnung ist nach Nachrichtentyp getrennt:

Nachricht	Nativer Vertrag
`ORDERS`, `ORDRSP`, `APERAK`	Verzeichnis D.96A oder D.25A gemäß aktivierter Profilrevision
`CONTRL`	Service-Nachricht 2.2 bei Syntaxversion 3 oder Service-Nachricht 4.1 bei Syntaxversion 4

CONTRL gehört damit nicht zu den D.96A-/D.25A-Verzeichnisnachrichten. Jede Nutzlast darf höchstens 16 MiB groß sein.

Lesen Sie Als Entwickler mit EDIFACT arbeiten, wenn Sie vor dem HTTP-Client EDIFACT-Bytes, Mapping-Pfade, kanonische Fixtures und die Entwicklungs-Testmatrix festlegen müssen. Diese Seite bleibt die technische Referenz für den Partner-API-Vertrag.

Die Basisroute einer Verbindung lautet:

text

/api/v1/b2b-exchange/partner/connections/{connectionID}

Ein Partner darf mehrere aktive api.v1-Verbindungen besitzen. Behandeln Sie jede konkrete connectionID als getrennten Vertrag: Sie bindet genau ihre Inbox und ihre ausgehende Mailbox, nicht die Mailboxen anderer Verbindungen desselben Partners.

API-Key und Scopes binden

Dieser Pfad akzeptiert ausschließlich einen tenantfesten Workspace-API-Key. Senden Sie ihn im üblichen Bearer-Format:

http

Authorization: Bearer <api-key-id>:<secret>

Der API-Key muss derselben Identity und demselben Mandanten wie die aktive api.v1-Verbindung zugeordnet sein. Session, Client Credential, falscher Mandant, fremde Verbindung und fehlender Scope sind keine Alternativen.

Methode und Pfad	Exakter Scope
`POST /inbox`	`b2b_exchange_partner_inbox:create`
`GET /mailbox`	`b2b_exchange_partner_mailbox:list`
`POST /mailbox/{deliveryAttemptID}/claim`	`b2b_exchange_partner_mailbox:claim`
`GET /mailbox/{deliveryAttemptID}/payload`	`b2b_exchange_partner_mailbox:payload_read`
`POST /mailbox/{deliveryAttemptID}/acknowledge`	`b2b_exchange_partner_mailbox:acknowledge`

Nutzen Sie getrennte API-Keys, wenn ein Client nur hochladen oder nur die Mailbox abarbeiten soll. Speichern Sie das Secret in einem Secret Store und nie in Quellcode, URL, Log oder Fehlermeldung.

`ORDERS` idempotent senden

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/inbox

Senden Sie genau ein EDIFACT-Interchange als unveränderten Request-Body:

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/inbox HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>
Content-Type: application/edifact
Idempotency-Key: orders-4711-attempt-1

<EDIFACT bytes>

Alternativ ist application/octet-stream zulässig. Workspace speichert die Nutzlast als application/edifact. Der Idempotency-Key ist Pflicht, darf höchstens 200 Zeichen enthalten und akzeptiert nur Buchstaben, Ziffern sowie ., _, :, und -.

Verwenden Sie denselben Schlüssel für alle Netzwerkwiederholungen desselben Uploads. Verwenden Sie ihn nicht für eine geänderte Nutzlast. Der Schlüssel ist an Verbindung und Mandant gebunden.

Ergebnis	HTTP-Status	Bedeutung
Erster vollständiger Upload	`202 Accepted`	Workspace hat die Nutzlast gespeichert und zur Verarbeitung angenommen.
Wiederholung desselben abgeschlossenen Uploads	`200 OK`	Die Antwort verweist auf denselben Upload; `replay` ist `true`.
Zu große Nutzlast	`413 Payload Too Large`	Die 16-MiB-Grenze wurde überschritten.
Ungültiger Vertrag	`400 Bad Request`	Content-Type, Idempotenzschlüssel oder Request-Vertrag ist ungültig.
Widersprüchliche Wiederholung	`409 Conflict`	Schlüssel oder aktueller Upload-Zustand passt nicht zur Wiederholung.

Die Antwort enthält uploadId, optional interchangeId, status und replay. Speichern Sie uploadId und interchangeId als technische Korrelation, nicht als fachliche Bestellnummer.

Mailbox seitenweise lesen

GET/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox

Rufen Sie fällige, noch nicht geclaimte Auslieferungen ab:

http

GET /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox?limit=50 HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

limit ist optional, standardmäßig 50 und höchstens 100. Wenn meta.hasMore wahr ist, senden Sie meta.nextCursor unverändert als cursor des nächsten Aufrufs.

Jeder Eintrag enthält:

deliveryAttemptId für Claim, Payload und Acknowledge,
interchangeId als Korrelation,
messageType,
payloadSize und payloadSha256,
status und createdAt.

Verarbeiten Sie Einträge in der gelieferten Reihenfolge. Ein Eintrag verschwindet während eines aktiven Claims aus der Liste.

Eintrag claimen

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/claim

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/claim HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

Die Antwort enthält deliveryAttemptId, claimToken und expiresAt. Der Claim ist fünf Minuten gültig. Workspace speichert nur den Hash des Tokens. Bewahren Sie das Token ausschließlich im Arbeitsspeicher des Workers auf und schreiben Sie es nicht in URL, Queue-Payload, Log oder dauerhafte Fehleraufzeichnung.

Verwenden Sie dasselbe Token für Payload und Acknowledge. Wenn der Worker die Lease ablaufen lässt, wird der Eintrag kontrolliert erneut fällig oder nach ausgeschöpftem Versuchslimit als fehlgeschlagen markiert. Starten Sie während einer aktiven Lease keinen zweiten Claim-Versuch für denselben Eintrag.

Payload vollständig und verifiziert lesen

GET/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/payload

http

GET /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/payload HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

Setzen Sie zusätzlich den HTTP-Header X-B2B-Claim-Token auf das beim Claim erhaltene Token.

Die Antwort ist ein EDIFACT-Byte-Stream mit Cache-Control: no-store und liefert diese Integritätsinformationen:

Feld	Bedeutung
`X-B2B-Payload-Size`	Erwartete Anzahl Bytes.
`X-B2B-Payload-SHA256`	Erwarteter SHA-256-Hash in Hex-Schreibweise.
Trailer `X-B2B-Payload-Integrity`	Nach vollständigem Lesen `verified`; bei Abbruch oder Abweichung `failed`.

Lesen Sie den Body bis EOF. Zählen Sie dabei die Bytes und berechnen Sie den SHA-256-Hash. Verarbeiten Sie die Nachricht nur, wenn Größe und Hash passen und der HTTP-Client nach EOF den Trailerwert verified sieht. Ein erfolgreicher Status vor EOF reicht nicht aus.

Workspace protokolliert das Öffnen sowie den verifizierten oder fehlgeschlagenen Abschluss als Auditereignis, ohne die Nutzlast oder ihren Hash in das Auditlog zu kopieren. Ein vorzeitig geschlossener Stream bleibt ein fehlgeschlagener Leseabschluss.

Auslieferung bestätigen

POST/api/v1/b2b-exchange/partner/connections/{connectionID}/mailbox/{deliveryAttemptID}/acknowledge

Bestätigen Sie erst nach vollständiger lokaler Speicherung und erfolgreicher Integritätsprüfung:

http

POST /api/v1/b2b-exchange/partner/connections/<connection-id>/mailbox/<delivery-attempt-id>/acknowledge HTTP/1.1
Authorization: Bearer <api-key-id>:<secret>

Setzen Sie auch hier den HTTP-Header X-B2B-Claim-Token auf dasselbe Token.

Die Antwort enthält deliveryAttemptId, receiptId, acknowledgedAt und replay. Wiederholen Sie Acknowledge nach einem unklaren Netzwerkabbruch mit demselben Token. Eine bereits abgeschlossene Bestätigung liefert denselben Receipt-Vertrag mit replay: true.

Bestätigen Sie nicht, wenn Download, EOF, Größe, Hash, Trailer oder lokale Speicherung fehlschlagen. Lassen Sie stattdessen die Lease auslaufen oder behandeln Sie den Vorfall nach Ihrer vereinbarten Betriebsprozedur.

Fehler ohne Informationsleck behandeln

Partnerantworten verwenden stabile Codes und geben keine internen Datenbankdetails, Tabellen, Dateipfade, Hostdetails oder rohen Treibertexte zurück.

HTTP-Status	Stabiler Code	Clientaktion
`400`	`ERR_B2B_EXCHANGE_INVALID_REQUEST`	Request lokal korrigieren; nicht unverändert wiederholen.
`404`	`ERR_B2B_EXCHANGE_NOT_FOUND`	Lokale Connection-ID, Key-Bindung, Scope, Claim und Lease prüfen; keine fremden IDs ausprobieren.
`409`	`ERR_B2B_EXCHANGE_CONFLICT`	Idempotenz oder Zustandswechsel prüfen und kontrolliert neu lesen.
`413`	`ERR_B2B_EXCHANGE_PAYLOAD_TOO_LARGE`	Nutzlast auf höchstens 16 MiB begrenzen.
`503`	`ERR_B2B_EXCHANGE_UNAVAILABLE`	Mit Backoff wiederholen; Korrelation und Zeitpunkt sichern.
`500`	`ERR_B2B_EXCHANGE_INTERNAL`	Nicht aus der Meldung auf interne Details schließen; Betreiber mit Korrelation informieren.

Loggen Sie nur HTTP-Status, stabilen Code, eigene Korrelation, connectionID, deliveryAttemptID und Zeitpunkt. Loggen Sie niemals API-Key, Claim-Token oder EDIFACT-Nutzlast.

Worker-Ablauf umsetzen

Ein robuster Mailbox-Worker folgt immer derselben Reihenfolge:

Mailbox mit Cursor lesen.
Einen Eintrag claimen.
Payload mit Claim-Token bis EOF lesen.
Bytezahl, SHA-256 und Integritätstrailer prüfen.
Nutzlast lokal dauerhaft und idempotent verarbeiten.
Mit demselben Claim-Token bestätigen.
Erst danach den nächsten Eintrag übernehmen.

Die Betriebs- und Konfigurationsseite für Administratoren finden Sie unter B2B Exchange betreiben.