1.  Herstellung der Verbindung für den Datenaustausch

       1.1 Herstellung der Verbindung mit dem Online-Shop - WooCommerce 

       1.2. Herstellung der Verbindung in MetaKocka

2. Synchronisation der Produkte

        2.1. Produktvariationen

        2.2. Zusätzliche Produktbeschreibungen

        2.3. Preissynchronisation

6. Zusätzliche Optionen für die Übertragung von Bestellungen aus dem Online-Shop in MetaKocka

6.1. Zuordnung spezifischer Länderfelder
6.2. Zuordnung der Steuernummer des Unternehmens
6.3. Zusätzliche Parameter für den Kunden/Empfänger
6.4. Standardstatus der Zahlungsinstrumente
6.5. Unterstützung für Nordirland

7. Bestellübersicht - für Entwickler 

8. Produktbestand aktualisieren - für Entwickler 

9. Produktübersicht - für Entwickler 

10. Opis pogostih napak

    10.1. Fehler bei der Übertragung 

    10.2. Fehler bei der Testverbindung 

    10.3. Fehler bei der Synchronisation von Produkten mit Variationen 

1. Herstellung der Verbindung für den Datenaustausch / Synchronisation

Die Integration eines Online-Shops auf der WooCommerce-Plattform mit MetaKocka ermöglicht:

- die automatische Übertragung von Bestellungen mit allen Kundendaten (Empfänger, Rechnungszahler, Zahlungsart, Rabatte und bestellte Produkte)

- die Synchronisation der Produkte (Produkte können aus dem Online-Shop mit allen bereits eingegebenen Daten in MetaKocka übertragen werden, sofern sie eine SKU-Nummer enthalten)

- die automatische Bestandsaktualisierung von MetaKocka in den Online-Shop. Es ist wichtig, dass der Lagerbestand im Online-Shop zuerst korrekt eingerichtet ist

Rechnungen, die auf Basis der automatisch übertragenen Bestellungen ohne zusätzlichen Aufwand generiert werden, werden für gesetzlich vorgeschriebene Zahlungsmittel auch bei der FURS bestätigt. Der Bestand der gelieferten Waren wird entsprechend reduziert und, falls eingestellt, auch im Online-Shop aktualisiert.

1.1. Zur Herstellung der Verbindung mit dem WooCommerce-Shop müssen folgende Daten aus WooCommerce abgerufen werden:

• Webadresse des Shops (z. B. "www.meinshop.de")
• Consumer Key
• Consumer Secret

Der Vorgang zur Beschaffung dieser Daten wird im Folgenden dargestellt:

!!In neueren Versionen von WooCommerce ist der Prozess zur Generierung des API-Schlüssels etwas anders.!!

Kopieren Sie die oben genannten Daten, da Sie diese für die Hinzufügung der Verbindung in MetaKocka benötigen.

1.2. Nach der Anmeldung in MetaKocka fügen Sie unter Einstellungen / Verbindungen eine neue Verbindung hinzu, wie im untenstehenden Bild dargestellt:

Im Falle einer erfolgreichen Verbindung erhalten Sie nach dem Klicken auf die Schaltfläche "Verbindung testen eine Bestätigung. Wenn es Probleme oder Fehler gibt, können Sie das Tool/Programm Postman verwenden, um die Verbindung zu testen.

Der jede WooCommerce-Installation eine separate Einrichtung ist, kann es zu Kommunikationsproblemen zwischen MetaKocka und WooCommerce kommen. Bei Problemen ist es ratsam, zunächst zu testen, ob die Schnittstelle in WooCommerce korrekt eingerichtet ist. Wir empfehlen die Verwendung des Programms Postman.

Erstellen Sie ein Dokument: Kreuzen Sie an, wohin Ihre Bestellungen vom Online-Shop übertragen werden sollen

Nach der Aktivierung der Funktion "Automatische Bestellübertragung" werden die Bestellungen in MetaKocka übertragen.

Falls Sie möchten, dass der Bestellstatus auch im Online-Shop geändert wird, wenn die Bestellung versendet wurde (gilt bei Verwendung des Order Management Moduls), wählen Sie die Option "Versendete Pakete automatisch als versendet im Online-Shop kennzeichnen" und speichern Sie die Änderung.

!!Wenn der Online-Shop verbunden ist und die Produkte verknüpft sind, müssen noch die entsprechenden zusätzlichen Einstellungen vorgenommen werden, insbesondere wie Zahlungen übertragen werden und wie die Versanddienstleister festgelegt werden!!

Im Falle der Aktivierung "Lager für Bestandsynchronisation" wird alle 5 Minuten eine automatische Bestandsynchronisation in alle Online-Shops durchgeführt, wenn MetaKocka überprüft, ob sich der Bestand der synchronisierten Produkte geändert hat. Bei den Produkten, bei denen eine Änderung stattgefunden hat, werden die Daten an den Online-Shop gesendet.

2. Synchronisation der Produkte (Online-Shop > MetaKocka)

Produkte werden vom Online-Shop in MetaKocka übertragen. Für die Übertragung von Produkten und Bestellungen ist es erforderlich, dass die Produkte im Online-Shop eindeutige SKU-Codes haben.

Falls diese nicht festgelegt sind und Sie viele Produkte haben, kann dies im Woocommerce-Shop mit dem Plugin Sku Regenerator (oder einem ähnlichen Plugin) eingerichtet werden, das die Festlegung von SKU-Codes/Code-Überschreibungen ermöglicht.

2.1 Produktvariationen (z. B. Farben, Größen, Längen)

Wenn Sie im Online-Shop Produkte verkaufen, die Variationen haben (z. B. Farben, Größen), muss jedem Produkt eine SKU-Code zugewiesen werden, der dann mit der Artikelnummer in MetaKocka übereinstimmt. Ein Beispiel ist in den folgenden Bildern dargestellt. In diesem Fall wird die Bestellung der Produktvariation entsprechend auf das MetaKocka-Produkt abgebildet.

Wenn Produkte Variationen haben und Sie alle Produkte aus dem Online-Shop in MK übertragen möchten, kann der folgende Fehler auftreten. In diesem Fall muss in den "Zusätzlichen Einstellungen" die Version 1 der API aktiviert werden.

org.codehaus.jackson.map.JsonMappingException: Can not construct instance of com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCVariations, problem: no suitable creator method found to deserialize from JSON Number
at [Source: java.io.StringReader@552621b8; line: 1, column: 9343] (through reference chain: com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCItem["variations"])

2.2  Zusätzliche Produktbeschreibungen

Falls Sie zusätzliche Beschreibungen für die Anzeige von Produkten aus dem Online-Shop übertragen möchten, ist dies nur über die meta_data-Tags mittels des REST orders Aufrufs möglich.

Die Funktionalität muss zusätzlich in den Einstellungen aktiviert werden -

https://metakocka.freshdesk.com/a/solutions/articles/3000077086?lang=de

Npr. da bi želeli pod artiklom "Torbica" izpisati še dva opisa:

Z. B., wenn Sie unter dem Produkt "Handtasche" noch zwei zusätzliche Beschreibungen anzeigen möchten:

In diesem Fall muss im MK-Interface für Online-Shops die zusätzliche Option "productExtraDescription" aktiviert werden (wenden Sie sich an den Support, damit diese aktiviert wird). Die JSON-Struktur der Antwort des REST orders Aufrufs muss die Daten als zusätzliche Werte in meta_data enthalten:

2.3 Preis-Synchronisation

Die Preis-Synchronisation erfolgt von MetaKocka nach WooCommerce. Legen Sie den Preislisten fest, aus denen die Preise synchronisiert werden, und starten Sie die Preis-Synchronisation.

3. Einstellung des Präfixes für Bestellungen

Falls Sie mehrere Online-Shops haben, können Sie die Methode zur Einstellung des Präfixes vor jeder Bestellung in diesem Artikel einsehen: https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/

In der JSON-Struktur der Bestellung gibt es zwei Felder für die Bestellbezeichnung:

• "Id" – die Nummer, die intern verwendet wird, um doppelte Bestellungen zu erkennen oder Bestelldaten im WC-Shop zu ändern.
• "number" – die Bezeichnung, die an allen Stellen in MetaKocka bzw. im Order Management angezeigt wird.

"Id" wird nie geändert, da sie nur erhöht wird. Auf der anderen Seite kann "number" beliebig geändert werden (z. B. von "1001" zu "SLO-1001"), ohne dass es zu doppelten Bestellungen kommt. Die einzige Einschränkung ist, dass dies nur für Online-Shops gilt, die ab dem 1.1.2018 in MK hinzugefügt wurden. Falls der Shop vorher hinzugefügt wurde, müssen Sie den MK-Support fragen, ob der Parameter "useInternalIdForOrderId" überprüft werden kann.

4. Unterstützung für Upsell 

Falls Sie beim Kauf der Bestellung Upsell-Produkte anbieten, müssen folgende Voraussetzungen erfüllt sein:

• Der Upsell muss zeitlich begrenzt sein – zum Beispiel 12 Stunden. Während dieses Zeitraums darf die Bestellung nicht versendet werden, da sie auf die Upsell-Möglichkeit warten muss.
• Die Bestellung darf nicht den Status "processing" erhalten, da sie sonst in den Versand übergeht. Sie muss einen Zwischenstatus haben (z. B. "waiting-upsell"), und es muss auf der WC-Seite eine Funktion entwickelt werden, die den Bestellstatus nach einer bestimmten Zeit auf "processing" ändert.
• Bei einer Statusänderung muss unbedingt ein Update über den Webhook durchgeführt werden.

5. Festlegung von Losnummern

Falls für ein Produkt in MetaKocka Losnummern verwaltet werden (z. B. beim Verkauf von Lebensmitteln) und der Online-Shop keine Unterstützung für die Eingabe von Losnummern bietet, wird MetaKocka automatisch eine Losnummer beim Übertragen der Bestellung festlegen. Der Prozess ist wie folgt:

• Die Losnummer wird nur im Falle einer Übertragung auf Rechnung automatisch festgelegt.
• Das Produkt muss gekennzeichnet sein, dass Losnummern für es verwaltet werden.
• Der Rechnung wird automatisch das Lager zugewiesen, basierend auf den Unternehmenseinstellungen.
• Für ein Produkt mit einer Losnummer wird im Lager überprüft, ob Bestand vorhanden ist. Falls Bestand vorhanden ist, wird die Losnummer mit der größten Menge im Lager ausgewählt.

Wenn für ein Produkt keine Losnummer festgelegt werden kann, wird beim Übertragen der Bestellung ein Fehler angezeigt und die Bestellung wird nicht übertragen. Beispiel für einen Fehler: 3952 - Janez Novak: Produkt 56 - m2 - Wildkastaniencreme 100 ml muss eine Losnummer haben.

6. Zusätzliche Optionen für die Übertragung von Bestellungen aus dem Online-Shop in MetaKocka

6.1. Zuordnung spezifischer Länderfelder 

In bestimmten Ländern sind zusätzliche Bezeichnungen in Adressen wichtig (insbesondere Provinzen). Daher sind unten die Regeln aufgeführt, wie die Adresse in WC eingegeben werden muss, damit sie korrekt in MK-Adressen übertragen wird.

Mapping der Rumänienfelder für die Verwendung im Adresseditor - Programm

Um korrekte Adressen in der Address Editor-Anwendung zu überprüfen, müssen die Adressinformationen auf eine bestimmte Weise bereitgestellt werden. Nachstehend finden Sie ein Beispiel für eine JSON-Anfrage von der WC-Seite (sie enthält nur die relevanten Felder). Die Feldnamen müssen genau so lauten wie im Beispiel unten und genau wie die Metadaten des Belegs (also nicht Partner, Artikel usw.). Bei der unten stehenden Anfrage wird die Adresse für den Kunden auf „Straße 1, BL:12 SC:D ET:4 AP:17“ und für den Empfänger auf „Straße 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2“ gesetzt.

WC hat verschiedene Versionen der API-Schnittstelle (aktuell ist Version v3). MK arbeitet standardmäßig mit der Schnittstelle v1. Wenn die Entwickler eine Aktualisierung auf WC vornehmen, weisen Sie sie auf Folgendes hin:

• Sie sollten die Aktualisierung auf Version V1 vornehmen,
• eine Aktualisierung auf Version V3 ist möglich, aber es muss in den "Zusätzlichen Einstellungen" für diesen Webshop die "API-Version" auf "V2" eingestellt werden.

Hinweis: Ergänzungen müssen in den folgenden Bereichen der WC-Schnittstelle vorgenommen werden:

• Auslösen des Webhooks und des MK-Aufrufs (dabei wird die vollständige JSON-Bestellung übermittelt)
• Rückgabe von Bestellungen über den API-Aufruf /orders

Im Feld "address_2" muss die Hausnummer angegeben werden. Dies erfolgt wie folgt:

• In der WC-Shop-Oberfläche muss der Benutzer die Straße und die Hausnummer separat eingeben,
• die Hausnummer muss im Feld "address_2" des Partners/Empfängers in der JSON-Antwort von WC eingetragen werden,
• in MK muss in jedem RO-Shop die Option "Daten aus Adressen als eine Adresse zusammenführen" aktiviert sein - mehr

[{    "id": 473216,    "parent_id": 0,    "billing": {      "address_1": "Ulica 1",      "address_2": "1"    },    "shipping": {      "address_1": "Ulica 2",      "address_2": "2"    },    "meta_data": [{        "id": 10736392,        "key": "_billing_address_bl",        "value": "BL:12"      }, {        "id": 10736393,        "key": "_billing_address_sc",        "value": "SC:D"      }, {        "id": 10736394,        "key": "_billing_address_et",        "value": "ET:4"      }, {        "id": 10736395,        "key": "_billing_address_ap",        "value": "AP:17"      }, {        "id": 10736399,        "key": "_shipping_address_bl",        "value": "BL:12_2"      }, {        "id": 10736400,        "key": "_shipping_address_sc",        "value": "SC:D_2"      }, {        "id": 10736401,        "key": "_shipping_address_et",        "value": "ET:4_2"      }, {        "id": 10736402,        "key": "_shipping_address_ap",        "value": "AP:17_2"      }    ]  }]

6.2. Mapping der Steuernummer des Unternehmens 

Wenn Sie in Ihrem Online-Shop die Ausstellung von Rechnungen an Unternehmen ermöglichen und ein Feld für die Eingabe der Steuernummer haben, können Sie diese Daten über die JSON "meta_data" an MK übertragen. Es gelten folgende Regeln:

• buyer_tax_id / receiver_tax_id – Steuernummer des Käufers bzw. des Empfängers. Wenn ein Wert angegeben ist, wird der Partner automatisch in MK als "Unternehmen" und "Steuerpflichtiger" markiert.
• buyer_tax_payer / receiver_tax_payer – Wenn der Wert "false" enthält, wird das Unternehmen in MK als nicht steuerpflichtig gekennzeichnet. Wie bereits erwähnt, wird das Unternehmen automatisch als steuerpflichtig gekennzeichnet, wenn kein Wert angegeben wird. 

Hinweis: Die Erweiterung muss in den folgenden Bereichen der WC-Schnittstelle vorbereitet werden:

• Auslösen des Webhooks und Aufruf von MK (dabei wird das gesamte JSON der Bestellung gesendet)
• Rückgabe der Bestellungen über den API-Aufruf /orders
  
  

Hinweis: Standardmäßig verwendet MK die V1 REST-Schnittstelle. Wenn Sie die Markierungen nur in der V2-Schnittstelle hinzugefügt haben, muss die Einstellung unter "Zusätzliche Einstellungen" -> "Webshops" geändert werden. Wählen Sie den Shop aus und suchen Sie nach "API-Version" und stellen Sie ihn auf "V2".

6.3. Zusätzliche Parameter beim Namen des Käufers / Empfängers 

6.3. Zusätzliche Parameter beim Namen des Käufers / Empfängers

Wenn unter den Metadaten der Bestellung die Daten "_billing_comp" oder "_shipping_comp" vorhanden sind, wird dieser Name unter dem Namen des Käufers gespeichert. Zum Beispiel wird der Käufer im folgenden Fall den Namen "BillComp, Name1 Surname1" haben und der Empfänger "ShippComp, Name2 Surname".

6.4. Voreingestellte Status der Zahlungsmethoden

Wenn eine Bestellung in WooCommerce eingeht, wird der folgende Status je nach Zahlungsmethode festgelegt:

6.5. Unterstützung für Nordirland 

Wenn Sie in das Gebiet Nordirlands verkaufen, muss für das Land eine spezielle Kennzeichnung angegeben werden, damit alle Regeln im Zusammenhang mit OSS (z. B. getrennte Nummerierung) berücksichtigt werden. Die korrekten Steuersätze müssen weiterhin im Shop hinterlegt werden. Der Onlineshop muss in der API-Antwort eine der folgenden Bezeichnungen für das Land zurückgeben:

• Vereinigtes Königreich (UK) - Nordirland
• United Kingdom - Northern Ireland
• XI

7. Bestellübersicht 

Zunächst wird die entsprechende URL für die Bestellliste erstellt, die folgende Struktur hat:
[Basis-URL des Onlineshops] + /wp-json/wc/v1/orders?per_page=1&order=desc

Beispiel: https://mystore.com/wp-json/wc/v1/orders?per_page=1&order=desc

Falls der Onlineshop HTTPS unterstützt, verwenden wir die Basic authentication, anderfalls OAuth. 

Die folgenden Abbildungen zeigen beide Methoden.

Am Ende sollte als Ergebnis ein JSON mit den Bestellungen zurückgegeben werden.

Nützliche Links:

• http://stackoverflow.com/questions/42186757/woocommerce-woocommerce-rest-cannot-view-status-401

8. Posodobitev zaloge artikla

Tip : POST

Primer klica : http://[moja trgovina]/wp-json/wc/v1/products/batch

Vsebina (3982 mora biti id artikla v spletni trgovini) :

8. Aktualisierung des Produktbestands

Typ: POST
Beispielaufruf: http://[moja trgovina]/wp-json/wc/v1/products/batch

Inhalt: (Dabei muss 3982 die Produkt-ID im Onlineshop sein):

{
"update" : [
{
"id" : 3982,
"stock_quantity" : 15000
}
]
}

Die Antwort ist die Ausgabe der Produktdaten, die "stock_quantity" : 15000 enthält.

9. Artikel- und Bestandsübersicht 

Typ : POST

Beispielaufruf: http://[moja trgovina]/wp-json/wc/v1/products/3982

Inhalt: keine

Die Antwort ist ein Produktdatenausdruck, der „stock_quantity“ mit dem entsprechenden Wert enthält.

10. Beschreibung häufiger Fehler

10.1. Fehler bei der Übertragung - Error parse respond 

Fehler

Error parse respond [eShopId : 280900507490] : org.codehaus.jackson.map.JsonMappingException: Invalid format: "2020-03-29T02:04:12" is malformed at "T02:04:12" (through reference chain: com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCOrder["date_paid"]) 

Der Fehler tritt auf, wenn die Zeit von Sommerzeit auf Winterzeit oder umgekehrt gewechselt wird.

Wenn auf Sommerzeit umgestellt wird, muss die Uhrzeit in WooCommerce auf UTC+2 (statt zuvor UTC+1) geändert werden.

Wenn auf Winterzeit umgestellt wird, muss die Uhrzeit in WooCommerce auf UTC+1 (statt zuvor UTC+2) geändert werden.

10.2.  Fehler bei der Verbindungstest

Im Falle einer erfolgreichen Verbindung erhalten Sie nach dem Klicken auf die Schaltfläche "Test Verbindung" eine Bestätigung. Wenn es jedoch Probleme/Fehler gibt, können Sie das Tool/Programm Postman zum Testen der Verbindung verwenden.
Da jede WooCommerce-Installation ihre eigene, separate Konfiguration hat, können Kommunikationsprobleme zwischen MetaKocka und WooCommerce auftreten. Es ist ratsam, zunächst zu testen, ob die Schnittstelle in WooCommerce korrekt eingerichtet ist. Wir empfehlen die Verwendung von Postman.

10.3 Fehler bei der Synchronisation von Produkten mit Varianten

Wenn Produkte Varianten haben und Sie alle Produkte aus dem Online-Shop in MK übertragen möchten, können Sie den folgenden Fehler erhalten. In diesem Fall müssen Sie in den "Zusätzliche Einstellungen" die Version v1 der API aktivieren.

org.codehaus.jackson.map.JsonMappingException: Can not construct instance of com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCVariations, problem: no suitable creator method found to deserialize from JSON Number

at [Source: java.io.StringReader@552621b8; line: 1, column: 9343] (through reference chain: com.metakocka.MetaKockaMain.server.GenericWebShop.WooCommerce.WooCItem["variations"])