Shopify | Hublify

Schnittstelle einrichten

Wähle Hublify im Shopify-App-Store https://apps.shopify.com/hublify und folge den dortigen Anweisungen zur Installation.
Nachdem du Hublify für deinen Shop authorisiert hast, wird die App für deine persönliche Hublify-Instanz aktiviert.

Bei Einrichten der Verbindung wird ein erster kleiner Test der Zugangsdaten durchgeführt und bei Erfolg wird deine Schnittstelle mit typischen Standard-Einstellungen konfiguriert.  Jetzt kannst du in der Hublify-App bereits auf Livedaten aus deinem Shopify-Shop zugreifen und könntest deine Auftrags- und Produktdaten synchronisieren.
Im Reiter „Bestehende Verbindungen“ findest du eine Übersicht mit den vorbereiteten Daten und kannst diese bei Bedarf weiter bearbeiten.

Im Folgenden findest du weitere Details zu spezielleren Einstellungen für Ex-/Importe.

Export-Einstellungen

Produktexport

{
   "dm_label": "product_to_shopify_<YourPOS>",         // Das ausgelagerte Data-Mapping
                                                        // Dort kannst du einstellen, welche deiner Hublify-Produktdatenfelder 
                                                        // welchen Shopify-Datenfeldern zugeordnet werden sollen.
    "iteratorParams": {
        "read_max": 1000,
        "show_inactive": true,
        "groupByVariant": true,                         // Bitte nicht entfernen. Dies wird für die in Shopify verwendete
                                                        // Artikel/Varianten-Struktur benötigt.
        "ngr_label": "product_groups"                   // Welcher Katalog soll verwendet werden. 
                                                        // Produkte, die keiner Kategorie aus diesem Katalog zugeordnet sind,
                                                        // werden automatisch herausgefiltert. 
    },
    "actionParams": {
        "autoLearn": true,                              // falls du bereits Produkte in Shopify angelegt hast, die noch nicht in den SyncMeta-Daten vermerkt sind, kannst du hierüber einstellen, dass nicht hinterlegte Produkte nicht automatisch neu angelegt werden, sondern erst geprüft wird, ob die entsprechende SKU bereits existiert.
        "inStock_unlimited": 9999,                      // an Shopify können nur reale Bestände übertragen werden. Hier kannst du festlegen, welcher Wert verwendet wird, falls du in Hublify ∞ als Lagerbestand nutzt
        "inventoryLocationId": <YourShopifyLocationId>, // die Shopify-Bestände sind an eine Location gebunden. Gib hier die Id der Location ein, für die in Shopify dein Inventar gepflegt werden soll. Vorbelegt wird dies mit der Default-Location deines Shops in Shopify.
        "publicationId": <YourShopifyPublicationId>,    // dies wird nur benötigt, wenn du Produkte mit einem Veröffentlichungsdatum in der Zukunft übergeben möchtest
        "img_export": {                                 // Sollen Bilder mit exportiert werden
            "active": true,                             // true = Bilder exportieren, false = Bildexport überspringen
            "image_only": false                         // true = Das Update der restlichen Daten wird übersprungen
        },
        "variant_groups_labels": {                      // Pro Produkt sind in Shopify nur 3 Variantenfelder erlaubt. Hier kannst du festlegen, wie deine Hublify Variantenfelder in Shopify benannt werden soll.
            "prdv_size": "Größe",
            "prdv_color": "Farbe",
            "prdv_other": "Anderes"
        },
        "variant_groups_labelFields": {
            "prdv_other": "other_variant_label"         // falls du pro Produkt unterschiedliche Variantenfelder übergeben möchtest, kannst du hier für jedes Variantenfeld ein Attribut aus deinen Produktdaten wählen, in das du das zugehörige Gruppenlabel eingetragen hast. Die zuvor gesetzten allgemeinen Einträge werden als Fallback genutzt.
        },
        "syme_sync_type": {
            "productgroup": "shopify_<YourPOS>",
            "product": "shopify_<YourPOS>",
            "asset": "shopify_<YourPOS>"
        }
    }
}

Target-Daten aus dem DataMapping:
Für jedes zu exportierende Produkt werden die folgenden Daten verwendet, die im DataMapping zugeordnet werden können.


/**
 * @param array $params
 * [internal_id] int (required) Hublify-ID for the product, usually the master-pcode
 * [fields] array (required) fields to push to shopify
 * [combinations] array (optional) array of combinations (aka variants) to push to shopify
 * [files_img] array (optional) array of images to push to shopify
 * [metafields][] array (optional) array of metafields to push to shopify
 *  [key] string (required) key of the metafield
 *  [value] string (required) value of the metafield
 *  [namespace] string (optional) namespace of the metafield
 *  [type] string (optional) type of the metafield
 **/

Meta-Fields

Falls du Daten als einzelne Felder/Attribute in Hublify gespeichert hast und diese als Metafield an Shopify übergeben möchtest,
musst du sicherstellen, dass du neben dem reinen Value auch den passenden Key, Namespace und falls nötig Type mit übergibst.
Sofern es dafür keine eigenen Felder gibt, kannst du diese im DataMapping fest eintragen

Beispiel:

...    
{
    "src": null,
    "trg": "metafields.0.key",
    "conversion": [
        {
            "active": true,
            "function": "set_value",
            "params": {
                "params": "yourmetafieldkey"
            }
        }
    ]
},
{
    "src": "hfyfieldforthisvalue",
    "trg": "metafields.0.value"
},
{
    "src": null,
    "trg": "metafields.0.namespace",
    "conversion": [
        {
            "active": true,
            "function": "set_value",
            "params": {
                "params": "yourmetafieldnamespace"
            }
        }
   ]
},
...

Import-Einstellungen

Auftragsimport

{
    "dm_label": "order_from_shopify_<YourPOS>",         // Das ausgelagerte Data-Mapping
                                                        // Dort kannst du einstellen, welche der Shopify-Auftragsdaten
                                                        // welchen Hublify-Datenfeldern zugeordnet werden sollen.
    "iteratorParams": {
        "ecs_enrich": true,                             // Bitte nicht entfernen, wird benötigt, um die Daten gezielt 
                                                        // für den Hublify-Import anzureichern
        "xcost": {
            "shipping_pcode": "VZK-001",                // Posten-PCode, der bei Versandkosten verwendet werden soll
            "shipping_name": "Versandkosten",           // Posten-Name, der bei Versandkosten verwendet werden soll
            "shipping_block": 5
       }
    },
    "actionParams": {
       "syme_sync_type": {
           "order": "shopify_<YourPOS>",                // Der Typ, unter dem die Aufträge in den SyncMeta-Daten erfasst werden
           "person": "shopify_<YourPOS>"                // Der Typ, unter dem die Kunden in den SyncMeta-Daten erfasst werden
       },
       "order_state_default": "shopify_create",              // Initial-Status angelegter Aufträge
       "order_state_create_success": "shopify_create_done",  // Auftragsstatus, wenn dieser erfolgreich importiert wurde
       "order_state_create_error": "shopify_create_failed",  // Auftragsstatus, falls es beim Import ein Problem gab
       "order_state_paid_success": "shopify_paid_done",      // Auftragsstatus, wenn der Auftrag als bezahlt eingegangen ist 
       "order_state_paid_error": "shopify_paid_failed",      // Auftragsstatus, falls ein Auftrag mit fehlgeschlagener Zahlung eingeht   
       "defaultParamsOnPurchase": {
           "beautify": true,
           "person_update": true,                            // soll der Kunden-Datensatz mit aktualisiert werden
       }
}

Im Normalfall werden alle offenen Bestellungen importiert.
Falls du auch ältere, bereits abgeschlossene Aufträge in Hublify importieren möchtest, kannst du die "iteratorParams" dahingehend anpassen.

Diese Einstellung solltest du aber bitte wieder entfernen, nachdem diese Aufträge importiert wurden.

{
    ...,
    "iteratorParams": {
        "get": {
            "status": "any"
        },
        ...
    }
}

Insbesondere wenn deine Aufträge länger offen in Shopify bleiben, weil du z.B. viele Vorbestellungen bekommst, empfehlen wir dir, nach dem Initialimport deine Einstellungen dahingehend anzupassen, dass nur noch die neuen/geänderten Aufträge abgerufen werden. Damit verhinderst du, dass du deine Datenabgleiche durch viele zusätzliche Doubletten-Checks ausbremst. Du kannst über den zusätzlichen Parameter "updated_at_min" den Zeitpunkt festlegen, ab dem Aufträge berücksichtigt werden sollen. Dafür bietet Hublify dir die Möglichkeit, relative Zeitangaben zu verwenden. Du solltest diese also passend zur Häufigkeit deiner Datenabgleiche einstellen, so dass du immer mindestens bis zum letzten Start deines Datenabrufs zurückgehst und am besten noch einen kleinen Zeitpuffer mit einplanst.

{
    ...,
    "iteratorParams": {
        "get": {
            "updated_at_min": "strtotime(-10days)"
        },
        ...
    }
}