# openTrans

> **openTrans** – Eingang und Ausgang. Der offene XML-Standard für B2B-Transaktionen. Kein Zusatz-Addon erforderlich.

## Überblick

openTrans ist ein freier XML-basierter Standard für Geschäftsdokumente. Viele deutsche ERP- und Warenwirtschaftssysteme (Sage, ProALPHA, abas, Microsoft Dynamics) können openTrans importieren oder exportieren – Orderport unterstützt openTrans sowohl als Eingang (wenn ein Partner openTrans liefert) als auch als Ausgang (wenn Ihr ERP openTrans erwartet).

Typische Anwendungsfälle:

- **Ausgang**: Eine cXML- oder Shopware-6-Bestellung wird nach openTrans XML übersetzt und an Ihr ERP gesendet.
- **Eingang**: Ein Partner liefert openTrans-XML, Orderport normalisiert und reicht es weiter – z. B. in ein anderes Zielsystem oder als JSON.

## Kompatibilität

### Unterstützte Versionen

| Bereich | Version |
|---|---|
| openTrans-Spezifikation | 2.1 |
| Content-Type | `application/xml` oder `text/xml` |
| Zeichenkodierung | UTF-8 |

### Bekannte Einschränkungen

- **Keine Invoice / Quotation / Shipping-Notice.** Nur das Transaktions-Dokument `ORDER` wird unterstützt, nicht `INVOICE`, `QUOTATION`, `DISPATCHNOTIFICATION` usw.
- **Keine Attachments.** `ATTACHMENT`-Blöcke werden ignoriert.
- **Custom-Extensions (`USERDEFINED_EXTENSIONS`)** werden durchgereicht, aber nicht in Standard-Mappings berücksichtigt.
- **Validierung**: Orderport validiert gegen die openTrans-DTD nicht strikt; fehlende Pflichtfelder werden erst vom empfangenden System bemerkt.

## Authentifizierung

openTrans selbst trägt keine Authentifizierung. Absichern über:

- **Bearer Token** oder **Shared-Secret-Header** an der Orderport-Webhook-URL (Eingang)
- **Basic-Auth** oder **OAuth** am ausgehenden Transport (Ausgang)

## Einrichten in Orderport

### Pipeline anlegen – openTrans als Ausgang

1. **Pipelines → Neue Pipeline**
2. Eingabeformat: Ihre Quelle (cXML, Shopware 6, EDIFACT, …), Ausgabeformat: **openTrans**
3. Auto-Mapping deckt Standard-Felder ab
4. Transport wählen: HTTP POST oder REST API an Ihr ERP (oft mit Basic-Auth)

### Pipeline anlegen – openTrans als Eingang

1. **Pipelines → Neue Pipeline**
2. Eingabeformat: **openTrans**, Ausgabeformat: **JSON** (oder ein anderes XML)
3. Auto-Mapping
4. Credential (Bearer Token / Shared-Secret-Header) anlegen, URL an den Absender geben

## Technische Details

### Beispiel (Ausgang)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ORDER version="2.1" type="standard">
  <ORDER_HEADER>
    <ORDER_INFO>
      <ORDER_ID>PO-2024-001</ORDER_ID>
      <ORDER_DATE>2024-03-15</ORDER_DATE>
      <PARTIES>
        <PARTY>
          <bmecat:PARTY_ID type="buyer_specific">BUYER-01</bmecat:PARTY_ID>
          <PARTY_ROLE>buyer</PARTY_ROLE>
          <ADDRESS>
            <NAME>Muster GmbH</NAME>
            <STREET>Hauptstr. 1</STREET>
            <ZIP>80331</ZIP>
            <CITY>München</CITY>
            <COUNTRY_CODED>DE</COUNTRY_CODED>
          </ADDRESS>
        </PARTY>
      </PARTIES>
      <ORDER_CURRENCY>EUR</ORDER_CURRENCY>
    </ORDER_INFO>
  </ORDER_HEADER>
  <ORDER_ITEM_LIST>
    <ORDER_ITEM>
      <LINE_ITEM_ID>1</LINE_ITEM_ID>
      <ARTICLE_ID>
        <SUPPLIER_AID>WIDGET-001</SUPPLIER_AID>
        <DESCRIPTION_SHORT>Premium Widget Blau</DESCRIPTION_SHORT>
      </ARTICLE_ID>
      <QUANTITY>10</QUANTITY>
      <ORDER_UNIT>PCE</ORDER_UNIT>
      <ARTICLE_PRICE>
        <PRICE_AMOUNT>150.00</PRICE_AMOUNT>
      </ARTICLE_PRICE>
    </ORDER_ITEM>
  </ORDER_ITEM_LIST>
  <ORDER_SUMMARY>
    <TOTAL_ITEM_NUM>1</TOTAL_ITEM_NUM>
    <TOTAL_AMOUNT>1500.00</TOTAL_AMOUNT>
  </ORDER_SUMMARY>
</ORDER>
```

### Zielfelder (wichtige Pfade)

| Pfad | Bedeutung |
|---|---|
| `ORDER_INFO.ORDER_ID` | Bestellnummer |
| `ORDER_INFO.ORDER_DATE` | Bestelldatum |
| `ORDER_INFO.ORDER_CURRENCY` | Währung |
| `ORDER_INFO.PARTIES.BUYER.NAME` / `.STREET` / `.ZIP` / `.CITY` / `.COUNTRY_CODED` | Käufer |
| `ORDER_INFO.PARTIES.SUPPLIER.*` | Lieferant |
| `ORDER_INFO.PARTIES.DELIVERY.*` | Lieferadresse |
| `ORDER_ITEM_LIST.ORDER_ITEM[].LINE_ITEM_ID` | Positionsnummer |
| `ORDER_ITEM_LIST.ORDER_ITEM[].ARTICLE_ID.SUPPLIER_AID` | Artikelnummer |
| `ORDER_ITEM_LIST.ORDER_ITEM[].ARTICLE_ID.DESCRIPTION_SHORT` | Beschreibung |
| `ORDER_ITEM_LIST.ORDER_ITEM[].QUANTITY` | Menge |
| `ORDER_ITEM_LIST.ORDER_ITEM[].ORDER_UNIT` | Mengeneinheit |
| `ORDER_ITEM_LIST.ORDER_ITEM[].ARTICLE_PRICE.PRICE_AMOUNT` | Einzelpreis |
| `ORDER_SUMMARY.TOTAL_AMOUNT` | Gesamtbetrag |

### Endpoint (Eingang)

Webhook-URL je Pipeline: `https://orderport.app/api/v1/webhook/{token}`.

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| ERP lehnt XML ab („DTD-Validierung fehlgeschlagen") | Pflichtfeld im Mapping nicht belegt | Im Mapping-Editor prüfen, welche `ORDER_INFO`-/`ORDER_ITEM`-Felder unbesetzt sind; per Static-Mapping füllen |
| Umlaute falsch dargestellt | ERP erwartet ISO-8859-1 statt UTF-8 | Transport auf HTTP POST mit `Content-Type: application/xml; charset=ISO-8859-1` konfigurieren (derzeit nicht UI-gestützt – manuelle Anpassung in Transport-Config) |
| Mengeneinheiten inkonsistent | Quelle liefert `EA`, openTrans-Kunden erwarten `PCE` | Transform-Mapping (`uppercase` + Static-Fallback) einbauen |

## Nächste Schritte

- [Feldmapping](/docs/feldmapping)
- [HTTP POST](/docs/http)
- [REST API](/docs/rest-api)