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#

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)#

{
  "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#

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#

Nächste Schritte#

• Feldmapping – Felder anpassen
• Zugangsdaten – HMAC im Detail
• Duplikatserkennung – wie Retries behandelt werden