Dokumentation: Shopify-Schnittstelle

Übersicht

Die Shopify-Schnittstelle ermöglicht eine bidirektionale Anbindung zwischen dem ERP-System (IPTOR Multiflex / Taskcenter) und Ihrem Shopify-Onlineshop. Folgende Funktionen werden unterstützt:

Voraussetzungen

1. Bestellimport (Order Import)

Funktionsweise

┌──────────────┐ Neue Bestellungen ┌──────────────────┐
│ Shopify │ ─────────────────────► │ Taskcenter │
│ (Webshop) │ automatisch/manuell │ (Auftrag) │
└──────────────┘ └──────────────────┘

Die Schnittstelle ruft automatisch neue Bestellungen aus Shopify ab und erstellt daraus Aufträge im Taskcenter.

Ablauf

1. Abruf: Bestellungen mit dem Status authorized oder paid werden aus Shopify geladen

2. Zahlungsinformationen: Für jede Bestellung werden die Transaktionsdaten abgerufen, um die Zahlungsart zu ermitteln

3. Kundenzuordnung: Rechnungs- und Lieferadresse werden übernommen

4. Positionsübernahme: Alle Bestellpositionen werden mit Artikelnummer (SKU), Menge, Preis und Steuer importiert

5. Auftragserstellung: Ein neuer Auftrag wird im Taskcenter angelegt

Importierte Daten

Konfiguration

Fehlerbehandlung

Schlägt der Import einer Bestellung fehl, wird das Erstellungsdatum der fehlerhaften Bestellung gespeichert. Beim nächsten Importlauf werden Bestellungen ab diesem Zeitpunkt (minus 1 Stunde Puffer) erneut abgerufen, sodass keine Bestellungen verloren gehen.

2. Produktexport (Product Export)

Funktionsweise

┌──────────────────┐ Artikeldaten ┌──────────────┐
│ Taskcenter │ ────────────────► │ Shopify │
│ (Artikelstamm) │ bei Änderungen │ (Produkt) │
└──────────────────┘ └──────────────┘

Geänderte Artikel werden automatisch als Shopify-Produkte exportiert. Dabei werden Artikeldaten, Bilder, Varianten und Metafelder übertragen.

Ablauf

1. Änderungserkennung: Artikeländerungen werden in einer Update-Warteschlange erfasst

2. Relevanzbewertung: Nur Artikel, die für den Webshop relevant sind, werden exportiert (siehe Artikelrelevanz)

3. Mapping: Artikelfelder werden gemäß der konfigurierten Feldzuordnung auf Shopify-Produktfelder gemappt

4. Transfer: Neue Produkte werden erstellt, bestehende aktualisiert

5. Bilder: Produktbilder werden als Base64 übertragen und Varianten zugeordnet

6. Archivierung: Artikel, die nicht mehr relevant sind, werden in Shopify archiviert

Artikelrelevanz

Die Schnittstelle unterstützt drei Methoden zur Bestimmung, welche Artikel exportiert werden:

Feldzuordnung (Mapping)

Die Zuordnung zwischen Taskcenter-Feldern und Shopify-Produktfeldern ist frei konfigurierbar:

Format-Strings

Feldzuordnungen unterstützen Platzhalter und Format-Strings:

{BEZEICHNUNG1} - {BEZEICHNUNG2}

Wird zu: Mein Artikel - Zusatztext
Für Dezimalwerte mit Punkt statt Komma:

{[VK1]}

Varianten

Artikel mit Varianten werden als ein Shopify-Produkt mit mehreren Varianten exportiert. Bis zu 3 Optionen (z. B. Größe, Farbe, Material) werden unterstützt. Die Zuordnung erfolgt über Felder mit dem Prefix variants..

Bilder

• Bilder werden aus dem konfigurierten Bilderpfad geladen

• Nur Bilder mit dem Kennzeichen „Internet" werden exportiert

• Bildarten 1 und 100–110 werden berücksichtigt

• Alt-Texte können über einen konfigurierbaren Format-String definiert werden (z. B. {BEZEICHNUNG1} - Bild {IMAGE.POSITION})

• Bilder können einzelnen Varianten zugeordnet werden

Preisfaktor

Exportierte Preise können mit einem konfigurierbaren Preisfaktor multipliziert werden (z. B. für Währungsumrechnung).

3. Lagerbestandsexport (Stock Export)

Funktionsweise

Geänderte Lagerbestände werden automatisch an den konfigurierten Shopify-Standort (Location) übertragen.

Übertragene Daten

{
    "location_id": 12345678,
    "inventory_item_id": 87654321,
    "available": 42
}

Voraussetzungen

• Ein Lager (Location) muss in der OE hinterlegt sein

• Die Artikelzuordnung (Inventory-Mapping) muss vorhanden sein

Zuordnung neu aufbauen

Über die Funktion „Bestandszuordnung neu aufbauen" wird die Zuordnungstabelle SHOPIFY_ARTIKEL_MAPPING vollständig neu erstellt. Dabei werden:

1. Alle aktiven Produkte aus Shopify geladen

2. Die SKU jeder Variante mit den Artikelnummern im Taskcenter abgeglichen

3. Neue Zuordnungen erstellt und veraltete entfernt

4. Auftragsstatus / Fulfillment (Order Status)

Funktionsweise

┌──────────────────┐ Lieferschein ┌──────────────┐
│ Taskcenter │ ────────────────► │ Shopify │
│ (Lieferschein) │ Fulfillment │ (Versandt) │
└──────────────────┘ └──────────────┘

Wenn im Taskcenter ein Lieferschein erstellt wird, meldet die Schnittstelle die betroffenen Positionen als Fulfillment an Shopify zurück. Der Kunde sieht dadurch im Webshop, dass seine Bestellung (teilweise) versendet wurde.

Ablauf

1. Bestellzuordnung: Über die Lieferscheinpositionen werden die zugehörigen Shopify-Bestellungen ermittelt

2. Fulfillment-Orders laden: Für jede betroffene Shopify-Bestellung werden die offenen Fulfillment-Orders abgerufen

3. Positionszuordnung: Die Lieferscheinpositionen werden den Fulfillment-Order-Positionen über die Inventory-Item-ID zugeordnet

4. Fulfillment senden: Ein Fulfillment-Request wird an Shopify gesendet

5. Mapping speichern: Die Fulfillment-ID wird für die spätere Tracking-Link-Übermittlung gespeichert

Teillieferungen

Die Schnittstelle unterstützt Teillieferungen. Wird nur ein Teil der bestellten Menge geliefert, wird nur dieser Teil als fulfilled gemeldet. Die restlichen Positionen bleiben in Shopify als offen bestehen.

5. Tracking-Links (Sendungsverfolgung)

Funktionsweise

┌──────────────────┐ Tracking-Daten ┌──────────────┐
│ Taskcenter │ ────────────────► │ Shopify │
│ (Versand/NVE) │ │ (Tracking) │
└──────────────────┘ └──────────────┘

Nach dem Versand werden Tracking-Links und Sendungsnummern an das zugehörige Shopify-Fulfillment übermittelt.

Übertragene Daten

Kundenbenachrichtigung

Über die Einstellung „Kunden benachrichtigen" (NotifyCustomer) kann gesteuert werden, ob Shopify den Kunden automatisch per E-Mail über die Versandinformation informiert.
Ablauf

1. Tracking-Daten werden aus der Tabelle BEX_NVE gelesen

2. Über das Fulfillment-Mapping wird die zugehörige Fulfillment-ID ermittelt

3. Die Tracking-Informationen werden an Shopify übermittelt

4. Bei Erfolg wird das Fulfillment-Mapping gelöscht und der Datensatz als exportiert markiert

6. Metafield-Management

Übersicht

Metafelder ermöglichen es, zusätzliche strukturierte Daten an Shopify-Produkte und -Varianten anzuhängen, die über die Standard-Produktfelder hinausgehen (z. B. technische Spezifikationen, SEO-Daten, benutzerdefinierte Attribute).

Konfiguration

Metafelder werden pro OE konfiguriert und können für zwei Ebenen definiert werden:

Metafeld-Eigenschaften

Feldzuordnung

Jedes Metafeld kann eine oder mehrere Spalten-Zuordnungen haben, die festlegen, woher die Daten kommen:

Beispiel: JSON-Metafeld

Konfiguration:

• Key: specifications

• Namespace: details

• Typ: json

• Mappings: GEWICHT → weight, Profiling.MATERIAL → material

Ergebnis in Shopify:

{
    "key": "specifications",
    "namespace": "details",
    "type": "json",
    "value": "{\"weight\": \"1.5\", \"material\": \"Edelstahl\"}"
}

Beispiel: Kumulierung aus Varianten

Wenn ein Produkt mehrere Varianten mit unterschiedlichen Farben hat und die Option „Kumulieren aus Varianten" aktiviert ist:

{
    "key": "available_colors",
    "namespace": "details",
    "type": "single_line_text_field",
    "value": "Rot,Blau,Grün"
}

Verhalten bei Aktualisierung

Beim Produktexport werden bestehende Metafelder im Namespace details gelöscht und neu erstellt. Dies stellt sicher, dass veraltete Daten nicht in Shopify verbleiben.

Fehlerbehandlung

Protokollierung

Alle API-Anfragen und -Antworten werden im Schnittstellenprotokoll erfasst. Bei aktiviertem Logging werden die JSON-Daten zusätzlich als Dateien gespeichert:
• *_Request.json – Gesendete Daten
• *_Response.json – Empfangene Antworten
• *_ResponseFault.json – Fehlerhafte Antworten

API-Kommunikation

Rate Limiting

Zwischen jedem API-Aufruf wird eine Pause von 500 ms eingehalten, um die Shopify API-Rate-Limits nicht zu überschreiten.

Paginierung

Bei großen Datenmengen (z. B. viele Produkte oder Bestellungen) wird die Shopify-Paginierung über den Link-Header automatisch verarbeitet. Pro Seite werden maximal 250 Einträge abgerufen.

Sicherheit

• Die Kommunikation erfolgt ausschließlich über HTTPS

• Die Authentifizierung erfolgt über den Header X-Shopify-Access-Token

• TLS 1.2 wird unterstützt

Support

Bei Fragen zur Einrichtung oder bei Problemen mit der Shopify-Schnittstelle wenden Sie sich bitte an Ihren Systemadministrator oder den technischen Support.