Als Entwickler mit EDIFACT arbeiten

Diese Entwicklerreferenz beschreibt, wie Sie einen EDIFACT-Partnervertrag für Workspace implementieren und testen. Sie richtet sich an Integratoren, die Mapping-Definitionen, Fixture-Nachweise oder einen Partner-API-Client bauen. Nach Abschluss besitzen Sie eine reproduzierbare Testkette von unveränderten EDIFACT-Bytes bis zum kanonischen Modell und zurück.

Die Seite ersetzt weder das vereinbarte Partnerprofil noch die Nachrichtenbeschreibung im UN/EDIFACT-Verzeichnis. Beginnen Sie mit EDI/EDIFACT verstehen und einführen und lassen Sie den Partner nach EDIFACT-Partner einrichten einrichten.

Entwicklungsgrenze festlegen

Teilen Sie die Implementierung in testbare Einheiten:

Diese Trennung ist der wichtigste Regression-Schutz. Lassen Sie einen Transportfehler nicht als APERAK erscheinen und behandeln Sie ein HTTP 202 Accepted nicht als fachliche Bestellannahme.

Bytes unverändert behandeln

EDIFACT ist ein Bytestromvertrag. Beachten Sie deshalb:

• Lesen Sie bis EOF und behandeln Sie einen abgebrochenen Stream als Fehler.
• Prüfen und speichern Sie Größe sowie SHA-256 der tatsächlich empfangenen Bytes.
• Normalisieren Sie keine Zeilenenden, Leerzeichen, Zeichensätze oder Servicezeichen vor der Integritätsprüfung.
• Erkennen Sie UNA, bevor Sie die übrigen Segmente zerlegen.
• Beachten Sie das Release-Zeichen. ?', ?+ und ?: sind Daten, keine Trenner.
• Begrenzen Sie einen Interchange auf 16 MiB. Workspace lehnt größere Nutzlasten ab.
• Verwenden Sie für HTTP Content-Type: application/edifact oder den dokumentierten Fallback application/octet-stream.

Wenn Ihr Client Dateien aus einem Texteditor übernimmt, prüfen Sie besonders Byte Order Marks, automatische Zeichensatzkonvertierung und angehängte Zeilenumbrüche. Ein visuell identischer Text kann einen anderen SHA-256-Wert besitzen.

Envelope vor Fachsegmenten prüfen

Validieren Sie mindestens diese Beziehungen, bevor ein Mapping läuft:

1. UNB und UNZ bilden einen vollständigen Interchange.
2. Kontrollreferenzen und angegebene Nachrichtenanzahl passen zusammen.
3. Jedes UNH besitzt ein passendes UNT.
4. UNT verweist auf die richtige Nachrichtenreferenz und Segmentanzahl.
5. Typ, Version, Release und Agency in UNH entsprechen der aktiven Profilrevision.
6. Syntaxversion und Servicezeichen entsprechen dem Verzeichnisvertrag.
7. Sender und Empfänger lösen auf den erwarteten Partner auf.

Verwenden Sie für diesen Schritt einen EDIFACT-fähigen Parser. Ein regulärer Ausdruck oder strings.Split bildet Release-Zeichen, Wiederholungen, Komponenten und Segmentgrenzen nicht zuverlässig ab.

Mapping-Definitionen versionieren

Eine Profilrevision enthält eine geschlossene, deklarative Mapping-Definition. Für eingehendes ORDERS zeigen Quellen auf EDIFACT-Pfade und Ziele auf SalesOrderRequestV1. Für ausgehendes ORDRSP ist die Richtung umgekehrt.

Ein EDIFACT-Pfad folgt diesem Modell:

SEGMENT[qualifierElement.qualifierComponent=wert].element.component#repetition

Beispiele:

Fehlende Komponenten- und Wiederholungsnummern bedeuten jeweils 1. Qualifier und Pfade müssen im gewählten Nachrichtenverzeichnis erlaubt sein. Ein syntaktisch plausibler, aber für ORDERS unbekannter Segmentpfad wird abgelehnt.

Dieses gekürzte Beispiel zeigt das Format einer eingehenden Definition. Es ist bewusst kein vollständiges produktives Mapping:

{
  "version": 1,
  "directory": "D.96A",
  "messageType": "ORDERS",
  "direction": "inbound",
  "canonicalType": "SalesOrderRequestV1",
  "rules": [
    {
      "target": "schemaVersion",
      "operations": [{ "kind": "constant", "value": "1" }],
      "required": true
    },
    {
      "target": "externalOrderRef",
      "sources": ["BGM.2.1"],
      "operations": [{ "kind": "normalize", "format": "trim" }],
      "required": true
    },
    {
      "target": "orderedAt",
      "sources": ["DTM[1.1=137].1.2"],
      "operations": [
        {
          "kind": "date",
          "format": "20060102",
          "outputFormat": "2006-01-02T15:04:05Z"
        }
      ],
      "required": true
    },
    {
      "target": "lines[].orderedQuantity.value",
      "sources": ["QTY[1.1=21].1.2"],
      "operations": [
        { "kind": "decimal", "decimalMark": ".", "scale": 3 }
      ],
      "required": true
    }
  ]
}

Der deklarative Vertrag unterstützt ausschließlich die freigegebenen Operationen constant, normalize, date, decimal, coalesce, code_map und unit_map. Unbekannte Felder, Skripte, nicht erlaubte Pfade, doppelte Ziele oder Widersprüche zwischen Richtung, Verzeichnis, Nachrichtentyp und kanonischem Typ werden abgelehnt.

Kanonisches Ergebnis prüfen

Ein gültiges eingehendes Mapping erzeugt SalesOrderRequestV1. Ein gekürztes, aber strukturell vollständiges Beispiel lautet:

{
  "schemaVersion": "1",
  "externalOrderRef": "PO-1001",
  "buyer": {
    "scheme": "GLN",
    "qualifier": "14",
    "value": "4000001000001"
  },
  "seller": {
    "scheme": "GLN",
    "qualifier": "14",
    "value": "4000002000008"
  },
  "orderedAt": "2026-07-16T00:00:00Z",
  "currency": "EUR",
  "lines": [
    {
      "lineNumber": 1,
      "item": { "gtin": "04012345000016" },
      "orderedQuantity": { "value": "2", "unit": "PCE" }
    }
  ]
}

Beachten Sie diese Invarianten:

• schemaVersion ist "1".
• Käufer, Verkäufer, externe Bestellreferenz, Bestelldatum und Währung sind eindeutig.
• Jede Position besitzt eine positive, eindeutige Positionsnummer.
• Mindestens GTIN, SKU oder Kundenartikelreferenz identifiziert den Artikel.
• Mengen sind positive Dezimalstrings ohne Komma oder Exponent.
• Externe Preise und Steuersätze sind Eingabedaten; Workspace prüft Preise, Steuern und Commerce-Bindung autoritativ.

Vergleichen Sie erwartetes JSON semantisch als geschlossenes kanonisches Objekt. Doppelte Schlüssel, unbekannte Felder, nachgestellte JSON-Werte oder ein leeres Expected-Payload sind keine gültige Fixture-Erwartung.

Fixture-Suite aufbauen

Legen Sie pro Partnerprofil eine kleine, aussagekräftige Suite an:

Speichern Sie Fixtures nicht als lose lokale Wahrheit. Legen Sie Eingabe und Expected als autorisierte Storage-Objekte an, binden Sie ihre SHA-256-Hashes an die Profilrevision und starten Sie die serverseitige Verifikation. Nach einer Änderung erstellen Sie einen neuen Nachweis; ein terminaler Nachweis wird nicht nachträglich umgedeutet.

Partner-API-Client robust implementieren

Der produktive Client arbeitet in zwei unabhängigen Schleifen:

ORDERS senden

1. Erzeugen Sie genau einen vollständigen Interchange.
2. Speichern Sie die Bytes lokal dauerhaft und berechnen Sie SHA-256.
3. Erzeugen Sie einen stabilen Idempotency-Key für genau diese Bytes.
4. Senden Sie die Bytes an /inbox.
5. Verwenden Sie bei einem unklaren Netzwerkresultat denselben Key und dieselben Bytes erneut.
6. Speichern Sie uploadId und interchangeId nur als technische Korrelationen.

Mailbox verarbeiten

1. Listen Sie fällige Auslieferungen mit Cursor.
2. Claimen Sie genau einen Eintrag.
3. Lesen Sie den Payload mit dem Claim-Token vollständig bis EOF.
4. Prüfen Sie Größe, SHA-256 und den abschließenden Integritätstrailer.
5. Speichern und verarbeiten Sie die Bytes lokal idempotent.
6. Bestätigen Sie erst danach mit demselben Claim-Token.

Der vollständige HTTP-Vertrag einschließlich Scopes, Headern, Statuscodes und Retry-Semantik steht in B2B-Exchange-Partner-API integrieren.

Fehler nach Stufe behandeln

Protokollieren Sie HTTP-Status, stabilen Fehlercode, eigene Korrelation, Connection-ID und Zeitpunkt. Protokollieren Sie niemals API-Key, Claim-Token, Credential, vollständige EDIFACT-Nutzlast oder interne Rohfehler.

Entwicklungsabnahme

Ihre Implementierung ist bereit, wenn:

• Parser und Mapping dieselben Fixtures reproduzierbar verarbeiten,
• positive und negative serverseitige Fixture-Nachweise erfolgreich sind,
• der echte Transport mit vollständiger Integritätsprüfung getestet ist,
• Netzwerkwiederholungen keine zweite Commerce-Wirkung erzeugen,
• der Client CONTRL, APERAK und ORDRSP getrennt verarbeitet,
• eine neue Partnerprofilversion eine neue unveränderliche Revision erzeugt, und
• Logs und Fehlerantworten keine Secrets oder Nutzdaten offenlegen.