# WooCommerce

> **WooCommerce** – Eingang via REST-API-Webhook (JSON). Benötigtes Addon: `connector_woocommerce`.

## Überblick

Orderport empfängt Bestellungen aus WooCommerce-Shops über den eingebauten Webhook-Mechanismus. Beim Order-Create-Event sendet WooCommerce die komplette Bestellung als JSON an Orderport. Orderport normalisiert die WooCommerce-spezifische Struktur und übergibt sie an Ihr Zielformat.

Die Integration unterstützt **nur den Eingang**. Bestellungen von Orderport zurück in WooCommerce zu schreiben, ist nicht Bestandteil dieser Integration.

## Kompatibilität

### Unterstützte Versionen

| Bereich | Version |
|---|---|
| WooCommerce | 6.x und neuer (REST API v3) |
| WordPress | 6.0+ |
| Event | `order.created` (und optional `order.updated`) |
| Signatur | HMAC-SHA256 über Base64-codiertes Secret |

### Bekannte Einschränkungen

- **Kein Rückweg.** Updates, Stornos oder Fulfillment-Statusänderungen werden nicht in WooCommerce zurückgeschrieben.
- **`order.updated`-Webhooks** werden zwar akzeptiert, aber wie `order.created` verarbeitet – Orderport erkennt die Bestellung per Bestellnummer als Duplikat und weist sie ab.
- **Coupons, Fee-Lines, Shipping-Lines** landen nicht im Standard-Mapping. Bei Bedarf manuell im Feldmapping ergänzen.
- **Produktvarianten** tauchen als eigene Positionen auf, werden aber nicht separat als Variante markiert.
- **Meta-Felder der Bestellung** (`meta_data`) werden nicht standardmäßig extrahiert.

## Authentifizierung

WooCommerce signiert jeden Webhook-Body mit HMAC-SHA256 im Header `X-WC-Webhook-Signature`. Orderport prüft die Signatur vor der Verarbeitung.

- **Auth-Typ in Orderport**: `HMAC-SHA256`
- **Header-Name**: `X-WC-Webhook-Signature`
- **Secret**: wird in WooCommerce beim Anlegen des Webhooks angegeben und muss identisch in Orderport hinterlegt werden

## Einrichten in Orderport

### Pipeline anlegen

1. **Pipelines → Neue Pipeline**
2. Eingabeformat: **WooCommerce**, Ausgabeformat nach Ihrem Ziel (**openTrans** oder **JSON**)
3. Auto-Mapping vorschlagen lassen und ggf. anpassen
4. Transport wählen

### Credential anlegen

Auf der Pipeline-Detailseite **Credentials → Hinzufügen**:

- Typ: **HMAC-SHA256**
- Header-Name: `X-WC-Webhook-Signature`
- Secret: selbst setzen (mindestens 8 Zeichen); denselben Wert in WooCommerce eintragen

## Einrichten im Shop

### Webhook konfigurieren

1. **WooCommerce → Einstellungen → Erweitert → Webhooks → Webhook hinzufügen**
2. Name: z. B. "Orderport"
3. Status: **Aktiv**
4. Thema: **Bestellung erstellt** (`order.created`)
5. Auslieferungs-URL: Webhook-URL aus Orderport
6. Geheimnis: identisch mit dem in Orderport hinterlegten HMAC-Secret
7. API-Version: **REST API v3**

## Technische Details

### Eingangs-Payload (Auszug)

```json
{
  "id": 1234,
  "number": "1234",
  "date_created": "2024-03-15T14:30:00",
  "status": "processing",
  "currency": "EUR",
  "total": "1500.00",
  "total_tax": "239.50",
  "billing": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "company": "Muster GmbH",
    "address_1": "Hauptstr. 1",
    "city": "München",
    "postcode": "80331",
    "country": "DE",
    "email": "bestellung@muster.de"
  },
  "shipping": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address_1": "Industriestr. 42",
    "city": "München",
    "postcode": "80331",
    "country": "DE"
  },
  "line_items": [
    { "sku": "WIDGET-001", "name": "Premium Widget Blau", "quantity": 10, "price": 150.00, "total": "1500.00" }
  ]
}
```

### Verfügbare Quellfelder

| Pfad | Bedeutung |
|---|---|
| `order.number` | Bestellnummer |
| `order.date` | Bestelldatum |
| `order.status` | WooCommerce-Status (`pending`, `processing`, `completed`, `cancelled`, …) |
| `order.currency` | Währungscode |
| `order.total` | Gesamtbetrag |
| `order.total_tax` | Steuer gesamt |
| `billing.first_name` / `last_name` / `company` / `email` | Rechnungsadressdaten |
| `billing.address` / `city` / `postcode` / `country` | Rechnungsadresse |
| `shipping.first_name` / `last_name` / `company` / `address` / `city` / `postcode` / `country` | Lieferadresse |
| `lines[].sku` / `name` / `quantity` / `price` / `total` | Positionen |

### Signaturprüfung

Orderport berechnet `base64(HMAC-SHA256(raw_body, secret))` und vergleicht zeitkonstant mit `X-WC-Webhook-Signature`. Bei Fehlschlag: HTTP 401.

### Endpoint

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

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| Webhook antwortet in WooCommerce mit „Failed delivery" | URL tippfehler oder Pipeline inaktiv | URL in der Pipeline-Detailseite kopieren; Pipeline aktivieren |
| Signaturprüfung schlägt fehl | WordPress fügt versteckte Leerzeichen oder BOM in den Body ein | Plugin **wp-super-cache** oder ähnliches deaktivieren oder nur für Admin-Routen ausschließen |
| Bestellstatus fehlt im Ziel | `order.status` wird nicht gemappt | Im Feldmapping ein Direct-Mapping ergänzen |
| Mehrere Webhooks für dieselbe Bestellung | WooCommerce sendet sowohl `order.created` als auch `order.updated` | Nur `order.created` einrichten, oder auf Orderports Duplikatserkennung vertrauen |

## Nächste Schritte

- [Feldmapping](/docs/feldmapping)
- [Zugangsdaten](/docs/credentials)
- [Duplikatserkennung](/docs/duplikatserkennung)