# Generisches JSON

> **Generisches JSON** – Eingang für beliebige JSON-Payloads mit einem reichen Schema für deutsche B2B-Bestellungen. Kein Zusatz-Addon erforderlich.

## Überblick

Nicht jedes System passt in eine der dedizierten Integrationen. Für individuelle Shop-Systeme, ERP-Exports, EDI-Konverter oder selbst entwickelte Webhooks bietet Orderport einen offenen JSON-Eingang. Orderport flacht die eingehende JSON-Struktur ab und stellt jedes Feld im Mapping-Editor zur Verfügung.

Das vordefinierte Schema ist speziell auf **deutsche/DACH-B2B-Bestellungen** ausgelegt: USt-ID, GLN, getrennte Liefer- und Rechnungsadressen, EANCOM-Mengeneinheiten, Steuersätze pro Position, Zahlungsbedingungen und Incoterms. Auto-Mapping für openTrans, JSON und JTL-Wawi ist vorhanden.

Die Integration unterstützt **nur den Eingang**.

## Kompatibilität

### Unterstützte Versionen

| Bereich | Version |
|---|---|
| Content-Type | `application/json` |
| JSON-Tiefe | unbegrenzt (praktisch: ≤ 10 Ebenen getestet) |
| Zeichenkodierung | UTF-8 |
| Zielformate mit Auto-Mapping | openTrans, JSON, JTL-Wawi |

### Bekannte Einschränkungen

- **Festes Beispiel-Dokument.** Der Mapping-Editor zeigt ein vordefiniertes DACH-B2B-Beispiel – Sie können **kein eigenes Payload hochladen**. Liefert Ihre Quelle Felder außerhalb des Schemas, tragen Sie diese Pfade im Editor manuell ein. Der Normalizer flacht trotzdem alles ab.
- **Kein Schema-Validator.** Orderport prüft nicht auf Pflichtfelder – stimmt ein Feld nicht mit der Erwartung, erkennt man das erst am Ergebnis.
- **Array-Handling** funktioniert via `[]`-Notation (`items[].sku`). Geschachtelte Arrays in Arrays werden unterstützt, können aber unübersichtlich werden.
- **Binäre oder base64-codierte Inhalte** innerhalb von Feldern werden unverändert durchgereicht – keine Dekodierung.

## Authentifizierung

Frei wählbar:

- **Bearer Token** – einfach, empfohlen für viele Partner
- **HMAC-SHA256** – wenn der Absender die Payload signieren soll
- **Shared-Secret-Header** – wenn ein individueller Custom-Header gebraucht wird

## Einrichten in Orderport

### Pipeline anlegen

1. **Pipelines → Neue Pipeline**
2. Eingabeformat: **Generisches JSON**, Ausgabeformat: **openTrans**, **JSON** oder **JTL-Wawi**
3. Auto-Mapping wird ausgeführt – ~22 Regeln werden vorgeschlagen (bei openTrans) bzw. ~20 (bei JSON)
4. Mapping bei Bedarf manuell anpassen
5. Für Felder, die Ihre Quelle liefert, aber nicht im vordefinierten Schema vorkommen: Zielfeld anklicken und den Quell-Pfad als Freitext eingeben (z. B. `metadata.partner_reference`)

### Credential

**Credentials → Hinzufügen**. Typ nach Anforderung des Absenders.

## Einrichten im Quellsystem

Sie senden die JSON-Payload per HTTP POST an die Webhook-URL. Das konkrete Setup hängt von Ihrem System ab:

- WordPress Plugin: cURL mit vorbereitetem Secret-Header
- Custom ERP-Export: Cron-Job, der nach jeder Bestellung einen POST absetzt
- Zapier/Make/n8n: HTTP-Action mit Auth-Header

## Auto-Mapping

Für drei Zielformate generiert Orderport Standard-Mappings, wenn Sie keine eigenen Regeln hinterlegen. Damit können Sie mit einer neuen Pipeline sofort loslegen.

| Ziel | Anzahl Standard-Regeln | Beispiele |
|---|---|---|
| **openTrans** (XML) | ~22 | `order.id` → `ORDER_INFO.ORDER_ID`, `buyer.company` → `PARTIES.BUYER.NAME`, `items[].sku` → `ORDER_ITEM.PRODUCT_ID` |
| **JSON** | ~20 | `order.id` → `order.id`, `buyer.company` → `customer.company`, `items[].unit_price_net` → `items[].price` |
| **JTL-Wawi** (XML) | ~30 | `order.id` → `order.cBestellNr`, `buyer.vat_id` → `customer.cUSTID`, `items[].ean` → `items[].cBarcode` |

## Technische Details

### Quellschema

Das Schema ist in acht Gruppen organisiert. Alle Pfade nutzen Punkt-Notation; Arrays werden mit `[]` gekennzeichnet.

#### Bestellkopf

| Pfad | Bedeutung |
|---|---|
| `order.id` | Bestellnummer |
| `order.number` | Bestellnummer (alternativ, z. B. bei SAP-Exporten) |
| `order.date` | Bestelldatum (ISO 8601) |
| `order.delivery_date` | Wunsch-Lieferdatum |
| `order.reference` | Käufer-Referenz / Projekt / Kostenstelle |
| `order.type` | `new`, `update`, `cancel` |
| `order.language` | `de`, `en`, `fr` |
| `order.comment` | Freitext-Notiz vom Käufer |

#### Beträge & Steuern

| Pfad | Bedeutung |
|---|---|
| `totals.currency` | ISO 4217 (`EUR`, `USD`, `CHF`) |
| `totals.net_amount` | Netto-Gesamtbetrag |
| `totals.gross_amount` | Brutto-Gesamtbetrag |
| `totals.tax_amount` | Steuer gesamt |
| `totals.shipping_amount` | Versandkosten |
| `totals.discount_amount` | Rabatt gesamt |

#### Käufer

| Pfad | Bedeutung |
|---|---|
| `buyer.gln` | GS1 GLN (13-stellig) |
| `buyer.company` | Firmenname |
| `buyer.contact_name` | Ansprechpartner |
| `buyer.email` | E-Mail |
| `buyer.phone` | Telefon |
| `buyer.vat_id` | USt-ID (`DE123456789`) |
| `buyer.street` | Straße + Hausnummer |
| `buyer.zip` / `buyer.city` / `buyer.country` | Anschrift |

#### Lieferadresse

| Pfad | Bedeutung |
|---|---|
| `delivery.gln` | GLN der Lieferstelle |
| `delivery.company` / `delivery.contact_name` | Empfänger |
| `delivery.street` / `delivery.additional` | Straße + Adresszusatz (z. B. „Tor 4") |
| `delivery.zip` / `delivery.city` / `delivery.state` / `delivery.country` | Anschrift |

#### Rechnungsadresse

| Pfad | Bedeutung |
|---|---|
| `invoice.company` | Firma |
| `invoice.street` / `invoice.zip` / `invoice.city` / `invoice.country` | Anschrift |
| `invoice.vat_id` | USt-ID (falls abweichend von `buyer.vat_id`) |

#### Positionen

| Pfad | Bedeutung |
|---|---|
| `items[].line_number` | Positionsnummer (1-basiert) |
| `items[].sku` / `items[].buyer_sku` | Artikelnummer (Lieferant + Käufer) |
| `items[].ean` | EAN / GTIN (13-stellig) |
| `items[].name` / `items[].description` | Kurzbezeichnung + ausführliche Beschreibung |
| `items[].quantity` / `items[].unit` | Menge + Mengeneinheit (PCE, KGM, LTR, MTR, TNE nach EANCOM) |
| `items[].unit_price_net` / `items[].unit_price_gross` | Einzelpreise |
| `items[].line_total_net` / `items[].line_total_gross` | Positions-Gesamtpreise |
| `items[].tax_rate` | Steuersatz (%) – z. B. 19 oder 7 |
| `items[].discount_percent` / `items[].discount_amount` | Positions-Rabatt |
| `items[].delivery_date` | Positions-spezifisches Lieferdatum |

#### Zahlung & Versand

| Pfad | Bedeutung |
|---|---|
| `payment.method` | `invoice`, `direct_debit`, `credit_card`, `advance` |
| `payment.terms` | z. B. „14 Tage netto, 2% Skonto bei 7 Tagen" |
| `payment.iban` / `payment.bic` | Bankdaten (optional) |
| `shipping.method` | DHL, DPD, UPS, Spedition |
| `shipping.incoterms` | EXW, FOB, CIF, DAP, DDP |

#### Metafelder (automatisch berechnet)

| Pfad | Bedeutung |
|---|---|
| `meta.item_count` | Anzahl Positionen (aus `items[]` abgeleitet) |
| `meta.total_line_amount` | Σ (Menge × Einzelpreis netto) |
| `meta.received_at` | Empfangs-Zeitstempel (ISO 8601) |
| `meta.received_date` / `meta.received_time` | Empfang als Datum und Uhrzeit |
| `meta.pipeline_name` | Name der empfangenden Pipeline |

### Beispiel-Payload

```json
{
  "order": {
    "id": "PO-2026-04-00123",
    "date": "2026-04-19T09:15:00+02:00",
    "delivery_date": "2026-04-26",
    "reference": "Projekt Alpha / Kostenstelle 4200",
    "type": "new",
    "language": "de",
    "comment": "Bitte Lieferung vor 12:00 Uhr an Tor 4."
  },
  "totals": {
    "currency": "EUR",
    "net_amount": 1500.00,
    "gross_amount": 1785.00,
    "tax_amount": 285.00
  },
  "buyer": {
    "gln": "4012345000009",
    "company": "Muster GmbH",
    "contact_name": "Max Mustermann",
    "email": "einkauf@muster.de",
    "vat_id": "DE123456789",
    "street": "Hauptstr. 1",
    "zip": "80331",
    "city": "München",
    "country": "DE"
  },
  "delivery": {
    "gln": "4012345000016",
    "company": "Muster GmbH – Zentrallager",
    "street": "Industriestr. 42",
    "additional": "Tor 4",
    "zip": "80331",
    "city": "München",
    "country": "DE"
  },
  "invoice": {
    "company": "Muster GmbH",
    "street": "Hauptstr. 1",
    "zip": "80331",
    "city": "München",
    "country": "DE",
    "vat_id": "DE123456789"
  },
  "items": [
    {
      "line_number": 1,
      "sku": "WIDGET-001",
      "ean": "4003969945418",
      "name": "Premium Widget Blau",
      "quantity": 10,
      "unit": "PCE",
      "unit_price_net": 150.00,
      "tax_rate": 19
    },
    {
      "line_number": 2,
      "sku": "KABEL-025",
      "name": "Anschlusskabel 2,5 m",
      "quantity": 5,
      "unit": "MTR",
      "unit_price_net": 12.80,
      "tax_rate": 19
    }
  ],
  "payment": {
    "method": "invoice",
    "terms": "14 Tage netto, 2% Skonto bei 7 Tagen"
  },
  "shipping": {
    "method": "DHL",
    "incoterms": "DAP"
  }
}
```

### Endpoint

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

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| Ihr reales Feld fehlt in der linken Spalte | Die Quelle liefert ein Feld außerhalb des vordefinierten Schemas | Zielfeld anklicken, Quell-Pfad als Freitext eingeben – der Normalizer akzeptiert jeden Pfad |
| Zielfelder bleiben leer | Quellpfad tippfehlerhaft oder Feldname groß-/kleinschreibungs-sensitiv | Pfad exakt so schreiben wie im Payload, inklusive Punkt-Notation |
| Array-Felder werden nicht expandiert | `[]`-Notation fehlt | `items[].sku` statt `items.sku` nutzen |
| Bestellnummer wird nicht erkannt (Duplikats-Check greift nicht) | Weder `order.id` noch `order.number` im Payload vorhanden | Bestellnummer unter einem der beiden Pfade liefern, oder per Transform-Mapping aus einem anderen Feld ableiten |

## Nächste Schritte

- [Feldmapping](/docs/feldmapping)
- [KI-Mapping](/docs/ai-mapping)
- [Zugangsdaten](/docs/credentials)