# Shopify

> **Shopify** – Eingang via Order-Webhook (JSON). Benötigtes Addon: `connector_shopify`.

## Überblick

Shopify sendet bei neu aufgegebenen Bestellungen einen Webhook an Orderport. Orderport normalisiert die Shopify-spezifische JSON-Struktur und wandelt sie in Ihr Zielformat (openTrans oder JSON) – damit Sie Shopify-Bestellungen in Ihr ERP, Ihre Warenwirtschaft oder an ein B2B-Netzwerk weitergeben können.

Die Integration unterstützt **nur den Eingang**. Bestellungen aus anderen Quellen in Shopify zurückzuschreiben, ist nicht möglich.

## Kompatibilität

### Unterstützte Versionen

| Bereich | Version |
|---|---|
| Shopify Admin API | 2024-01 und neuer (Webhook-Schema stabil) |
| Event | `orders/create` (Order creation) |
| Content-Type | `application/json` |
| Signatur | HMAC-SHA256 (Shopify-Standard) |

### Bekannte Einschränkungen

- **Kein Rückweg.** Bestell-Änderungen, Fulfillment- oder Zahlstatus-Updates aus anderen Quellen schreibt Orderport nicht nach Shopify zurück.
- **Nur Order-Creation-Events.** Spätere Events (`orders/updated`, `orders/paid`, `orders/fulfilled`) werden aktuell nicht ausgewertet – richten Sie nur `orders/create` ein.
- **Abonnements, Entwürfe und Draft-Orders** werden nicht unterstützt, nur abgeschlossene Bestellungen.
- **Line-Item-Properties** (Custom-Felder) werden nicht ausgewertet. Falls Sie Custom-Attribute benötigen, bitte melden.
- **Mehrere Locations/Fulfillment-Splits** werden auf eine einzelne Lieferadresse reduziert.

## Authentifizierung

Shopify signiert jeden Webhook-Body mit HMAC-SHA256 im Header `X-Shopify-Hmac-Sha256`. Orderport prüft die Signatur bei jeder eingehenden Anfrage.

- **Auth-Typ in Orderport**: `HMAC-SHA256`
- **Header-Name**: `X-Shopify-Hmac-Sha256`
- **Shared Secret**: wird bei der Credential-Anlage einmalig angezeigt und muss identisch in Shopify eingetragen werden.

## Einrichten in Orderport

### Pipeline anlegen

1. **Pipelines → Neue Pipeline**
2. Eingabeformat: **Shopify**, Ausgabeformat: **openTrans** oder **JSON**
3. Mapping-Vorschläge werden automatisch generiert
4. Transport wählen: HTTP, REST API, E-Mail oder FTP/SFTP je nach Zielsystem

### Credential anlegen

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

- Typ: **HMAC-SHA256**
- Header-Name: `X-Shopify-Hmac-Sha256`
- Secret: wird automatisch generiert (Format `ot_hmac_…`) – einmalig anzeigen und in Shopify eintragen

### Mapping

Standard-Mapping deckt Bestellnummer, Datum, Währung, Summen, Steuer, Kundenname, Lieferadresse und Positionen ab. Anpassungen (z. B. Bestellname `#1001` vs. Order-Number `1001`) lassen sich im Mapping-Editor vornehmen.

## Einrichten im Shop

### Webhook konfigurieren

1. **Settings → Notifications → Webhooks** → **Create webhook**
2. Event: **Order creation**
3. Format: **JSON**
4. URL: Webhook-URL aus Orderport (`https://orderport.app/api/v1/webhook/{token}`)
5. Webhook API version: **2024-01** oder neuer
6. Shopify legt das Secret automatisch an; tragen Sie es in Orderport als HMAC-Secret ein

> **Hinweis:** Shopify erzeugt das Secret und zeigt es im Admin-Bereich unter *Settings → Notifications* an. Das Secret ist pro Shop gleich – wenn Sie mehrere Pipelines haben, sollten Sie in Orderport dennoch pro Pipeline eine eigene Credential mit dem gleichen Secret anlegen.

## Technische Details

### Eingangs-Payload (Auszug)

```json
{
  "order_number": 1001,
  "name": "#1001",
  "created_at": "2024-03-15T14:30:00+01:00",
  "currency": "EUR",
  "total_price": "1500.00",
  "subtotal_price": "1260.50",
  "total_tax": "239.50",
  "financial_status": "paid",
  "customer": {
    "email": "bestellung@muster.de",
    "first_name": "Max",
    "last_name": "Mustermann"
  },
  "shipping_address": {
    "address1": "Industriestr. 42",
    "city": "München",
    "zip": "80331",
    "country_code": "DE"
  },
  "line_items": [
    { "sku": "WIDGET-001", "title": "Premium Widget Blau", "quantity": 10, "price": "150.00" }
  ]
}
```

### Verfügbare Quellfelder

| Pfad | Bedeutung |
|---|---|
| `order.number` | Bestellnummer numerisch |
| `order.name` | Bestellname (z. B. `#1001`) |
| `order.date` | `created_at` als ISO 8601 |
| `order.currency` | Währungscode |
| `order.total_price` | Gesamtbetrag inkl. Steuer |
| `order.subtotal_price` | Zwischensumme vor Steuer |
| `order.total_tax` | Steuer gesamt |
| `order.financial_status` | Zahlstatus (`paid`, `pending`, …) |
| `customer.email` / `first_name` / `last_name` / `company` | Kundendaten |
| `shipping.address1` / `city` / `zip` / `country_code` | Lieferadresse |
| `billing.address1` / `city` / `zip` / `country_code` | Rechnungsadresse |
| `lines[].sku` / `title` / `quantity` / `price` | Positionen |

### Signaturprüfung

Orderport berechnet `HMAC-SHA256(raw_body, secret)` und vergleicht das Base64-Ergebnis zeitkonstant mit dem Header `X-Shopify-Hmac-Sha256`. Bei Fehlschlag: HTTP 401 und Audit-Log-Eintrag `inbound.cxml_auth_failed`.

### Endpoint

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

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| 401 Unauthorized bei jedem Webhook | Secret in Orderport stimmt nicht mit Shopify überein | HMAC-Secret in Orderport neu anlegen und in Shopify eintragen |
| Währung wird nicht übernommen | `order.currency` fehlt in Payload (ältere API-Version) | API-Version auf 2024-01 oder neuer heben |
| Kundenfirma leer | Shopify sendet `customer.company` nur, wenn im Shop hinterlegt | Im Shopify-Adminfeld sicherstellen, dass Firma erfasst wird; Fallback via Static-Mapping möglich |
| Duplicate-Fehler bei Retry aus Shopify | Shopify sendet denselben Webhook bis zu 19-mal bei Fehlschlag | Orderport erkennt Duplikate automatisch anhand `order_number` – zweitem Webhook antwortet der Server mit 409 / Duplicate-Status |

## Nächste Schritte

- [Feldmapping](/docs/feldmapping) – Felder anpassen
- [Zugangsdaten](/docs/credentials) – HMAC im Detail
- [Duplikatserkennung](/docs/duplikatserkennung) – wie Retries behandelt werden