1. Integracja WooCommerce <> MetaKocka

The integration of the online store published on the Woocommerce platform with MetaKocka enables:

Integracja sklepu internetowego działającego na platformie WooCommerce z systemem MetaKocka umożliwia:

• automatyczne przesyłanie zamówień wraz ze wszystkimi danymi klienta (odbiorca, płatnik, forma płatności, rabaty oraz zamówione produkty),
• synchronizację produktów (produkty mogą być przesyłane ze sklepu internetowego do MetaKocka wraz ze wszystkimi danymi, które zostały już wprowadzone w sklepie internetowym, pod warunkiem że mają przypisany kod SKU),
• automatyczną synchronizację stanów magazynowych z MetaKocka do sklepu internetowego. Przed rozpoczęciem synchronizacji należy jednak przede wszystkim odpowiednio skonfigurować stany magazynowe w sklepie internetowym.

Faktury generowane są automatycznie na podstawie przesłanych zamówień, bez konieczności wykonywania dodatkowych czynności. Są one również weryfikowane w systemie FURS dla prawnie określonych metod płatności. W przypadku wydanych towarów stan magazynowy jest odpowiednio zmniejszany, a informacje o dostępności produktów są również aktualizowane w sklepie internetowym (jeżeli taka opcja została skonfigurowana).

1.1 Nawiązanie połączenia ze sklepem WooCommerce

Aby ustanowić połączenie ze sklepem WooCommerce, należy uzyskać z niego następujące dane:

• adres URL sklepu internetowego (np. „www.mystore.com”),
• Consumer Key,
• Consumer Secret.

Poniżej przedstawiono kroki wymagane do uzyskania tych danych:

W nowszych wersjach WooCommerce procedura generowania klucza API jest nieco inna! 

Skopiuj dane z powyższego miejsca – będą one potrzebne podczas dodawania połączenia z MetaKocka.

1.2. Po zalogowaniu do MetaKocka w zakładce Ustawienia/Połączenia należy dodać nowe połączenie, jak pokazano na poniższym obrazku:

Wybierz „WooCommerce” i kliknij „Dodaj” ("Add" ).

Wklej dane z WooCommerce – Consumer Key, Consumer Secret oraz adres URL – a następnie kliknij „Zapisz” (save).

Kliknij „Test połączenia” (test connection) – powinno pojawić się potwierdzenie, że integracja została pomyślnie nawiązana.

Dla modułu zarządzania zamówieniami wybierz „Zamówienia sprzedaży” (sales oreder, natomiast jeśli potrzebujesz jedynie tworzenia faktur, wybierz „Faktura” (Invoice).

Zaznacz opcję "Automatic order transfer", jeśli chcesz, aby wszystkie zamówienia otrzymane w WooCommerce były automatycznie przesyłane do MetaKocka. Jeżeli w WooCommerce konieczna jest ręczna edycja zamówień przed ich przesłaniem, pozostaw tę opcję niezaznaczoną.

Jeżeli wymagany jest ręczny transfer zamówień – wybierz, z ilu ostatnich dni mają zostać pobrane zamówienia, a następnie kliknij „Importuj zamówienia” (Import orders ).

2. Synchronizacja produktów (WooCommerce > MetaKocka) 

Produkty ze sklepu internetowego można automatycznie przesyłać do MetaKocka. Aby możliwe było przesyłanie produktów oraz zamówień, produkty w sklepie internetowym muszą posiadać unikalne kody SKU.

W przypadku dużej liczby produktów bez przypisanych kodów SKU można uporządkować je w sklepie WooCommerce za pomocą wtyczki SKU Regenerator, która umożliwia automatyczne przypisywanie lub kopiowanie kodów SKU.

Jeżeli w sklepie internetowym sprzedawane są warianty produktów (różne kolory, rozmiary itp.), konieczne jest przypisanie kodu SKU do każdego wariantu produktu. Kod SKU musi być taki sam jak kod produktu w MetaKocka.

Przykład został przedstawiony na poniższych obrazkach. W takim przypadku zamówione warianty produktów zostaną odpowiednio przypisane i skopiowane do właściwego produktu w MetaKocka.

Jeżeli chcesz przesłać wszystkie warianty produktów ze sklepu internetowego do MetaKocka, może pojawić się następujący błąd. W takim przypadku należy włączyć wersję API v1 w sekcji ''Additional Settings''. 

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 Dodatkowy opis produktu

Jeżeli chcesz przesyłać dodatkowe opisy produktu ze sklepu internetowego, można to zrealizować za pomocą oznaczeń meta_data w wynikach wywołania REST API zamówień.

Należy dodatkowo aktywować tę funkcjonalność w ustawieniach:

  https://metakocka.freshdesk.com/a/solutions/articles/3000077086

Przykład dla produktu „Torbica” chcemy dodać dwa dodatkowe opisy:

W takim przypadku należy aktywować dodatkową opcję „productExtraDescription” w interfejsie MetaKocka (w razie potrzeby można skontaktować się z działem obsługi klienta w celu uzyskania dodatkowej pomocy).

Struktura odpowiedzi JSON z wywołania REST API zamówienia musi zawierać dane jako dodatkowe wartości w polu meta_data:

3. Ustawienie prefiksu dla zamówień

Jeżeli korzystasz z większej liczby sklepów internetowych, sposób ustawienia prefiksu przed numerem poszczególnych zamówień można sprawdzić w poniższym artykule:
https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/

W strukturze JSON zamówienia znajdują się dwa pola służące do identyfikacji zamówienia:

• „Id” – numer używany wewnętrznie do wykrywania duplikatów zamówień lub do zmiany danych zamówienia w sklepie WooCommerce,
• „number” – oznaczenie (numer), które jest wyświetlane we wszystkich miejscach w MetaKocka oraz w module zarządzania zamówieniami.

Pole „Id” nigdy nie jest zmieniane, ponieważ może jedynie rosnąć. Natomiast pole „number” można dowolnie modyfikować (np. zmienić z „1001” na „SLO-1001”) i nie spowoduje to utworzenia zduplikowanych zamówień.

Jedynym ograniczeniem jest to, że funkcja ta działa dla sklepów internetowych dodanych do MetaKocka od dnia 01.01.2018.

W przypadku sklepu dodanego przed tą datą należy skontaktować się z pomocą techniczną MetaKocka w celu sprawdzenia ustawienia parametru „useInternalIdForOrderId”.

4. Obsługa Up-Sell

Jeżeli podczas zakupu produktu oferujesz klientowi możliwość zakupu dodatkowego produktu (Up-Sell), należy zapewnić następujące warunki:

• oferta Up-Sell musi być ograniczona czasowo – na przykład do 12 godzin. W tym czasie zamówienie nie może zostać wysłane, ponieważ musi oczekiwać na możliwość dodania produktu w ramach Up-Sell,
• zamówienie nie może otrzymać statusu „processing”, ponieważ spowodowałoby to bezpośrednią zmianę statusu na „dispatched ”. Należy przypisać dowolny przejściowy status (np. „waiting-upsell”), aby w określonym czasie możliwa była zmiana statusu na „processing”,
• w przypadku zmiany statusu obowiązkowe jest wykonanie aktualizacji poprzez webhook.

5. Określanie numerów partii (Lot numbers)

W przypadku prowadzenia numerów partii w MetaKocka (np. przy sprzedaży artykułów spożywczych), gdy sklep internetowy nie obsługuje wprowadzania numerów partii, MetaKocka automatycznie przypisze numery partii podczas przesyłania zamówień.

Procedura wygląda następująco:

• numer partii jest automatycznie przypisywany wyłącznie podczas transferu zamówienia do faktury,
• produkt musi być oznaczony jako taki, dla którego prowadzone są numery partii (Lot),
• faktura otrzymuje automatycznie przypisany magazyn zgodnie z ustawieniami firmy,
• w magazynie przypisanym do faktury system sprawdza, czy dla danego produktu z numerem partii istnieje dostępny stan magazynowy. Jeżeli tak, wybierany jest numer partii z największą ilością dostępnego towaru w magazynie,
• jeżeli produkt nie ma przypisanego numeru partii, podczas transferu zamówienia zostanie wyświetlony błąd, a zamówienie nie zostanie przesłane.

Przykład błędu:
3952 - Janez Novak: Product 56 - m2 - Wild chestnut ointment 100 ml must have a lot number assigned.

6. Dodatkowe możliwości przesyłania zamówień ze sklepu internetowego do MetaKocka

6.1. Mapowanie określonych pól dla krajów

W niektórych krajach dodatkowe oznaczenia w adresach (głównie województwa/prowincje) mają istotne znaczenie. Poniżej przedstawiono zasady wpisywania adresów w WooCommerce, aby zostały one prawidłowo skopiowane do adresów w MetaKocka.

Mapowanie pól dla Rumunii do wykorzystania w programie Edytor adresów

Aby sprawdzać poprawność adresów w aplikacji Edytor adresów, adresy muszą być przesyłane w określony sposób.

Poniżej znajduje się przykład żądania JSON ze sklepu WooCommerce (zawierający tylko istotne pola). Nazwy pól muszą być dokładnie takie same jak w poniższym przykładzie oraz zgodne z nazwami metadata dokumentu (nie partnera, produktów itp.).

Dla poniższego żądania adres kupującego zostanie ustawiony jako:

„Street 1, BL:12 SC:D ET:4 AP:17”

natomiast adres odbiorcy jako:

„Street 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2”.

WooCommerce posiada różne wersje interfejsu API (obecnie najnowsza wersja to v3). MetaKocka domyślnie pracuje z interfejsem v1.

Jeżeli programiści aktualizują interfejs WooCommerce, należy uwzględnić jedną z poniższych opcji:

• aktualizacja standardowo do wersji interfejsu V1,
• aktualizacja do wersji V3, ale w ustawieniach dodatkowych danego sklepu internetowego należy włączyć opcję:
  „Wersja API” – „V2”.

Uwaga: należy przygotować dodatkowe uzupełnienie dla następujących elementów interfejsu WooCommerce:

• aktywacja webhooka i wywołanie MetaKocka (przesyłany jest cały JSON zamówienia),
• zwracanie zamówień poprzez wywołanie API /orders.

W polu „address_2” należy dodać numer domu. Można to zrealizować w następujący sposób:

• w sklepie WooCommerce należy odpowiednio rozdzielić formularz danych użytkownika, aby użytkownik mógł osobno wprowadzić ulicę oraz numer domu,
• numer domu należy przesyłać w polu „address_2” partnera/odbiorcy w odpowiedzi JSON WooCommerce,
• w MetaKocka dla każdego sklepu RO należy włączyć opcję:
  „Grupuj dane z adresów jako jeden adres” – więcej informacji.

[{    "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. Mapowanie numeru podatkowego firmy

W przypadku włączenia możliwości wystawiania faktur również dla firm, a tym samym dodania pola do wprowadzania numeru podatkowego, dane te można łatwo przesyłać do MetaKocka za pomocą pola JSON „meta_data”.

Obowiązują następujące zasady:

• buyer_tax_id / receiver_tax_id – numer podatkowy kupującego (np. odbiorcy).
  Jeżeli wartość zostanie przekazana, partner w MetaKocka zostanie automatycznie oznaczony jako „firma” oraz „podatnik”.
• buyer_tax_payer / receiver_tax_payer – jeżeli pole zawiera wartość „false”, w MetaKocka firma zostanie oznaczona jako niebędąca podatnikiem.
  Zgodnie z powyższą zasadą – jeżeli wartość nie zostanie przekazana, firma zostanie automatycznie oznaczona jako podatnik.

Uwaga: należy przygotować dodatkowe uzupełnienie dla następujących elementów interfejsu WooCommerce:

• aktywacja webhooka i wywołanie MetaKocka (przesyłany jest cały JSON zamówienia),
• zwracanie zamówień poprzez wywołanie API /orders.

Uwaga: MetaKocka domyślnie korzysta z interfejsu REST API V1.

W przypadku dodania oznaczeń wyłącznie do interfejsu V2, należy zmienić ustawienia w sekcji:

„Ustawienia dodatkowe” → „Sklepy internetowe” → wybierz sklep → „Wersja API”

i ustawić wartość na „V2”.

6.3. Dodatkowe parametry w nazwie kupującego/odbiorcy

W przypadku znalezienia oznaczeń „_billing_comp” lub „_shipping_comp” w polu metadata, tylko ta wartość zostanie dodana przed nazwą kupującego.

Przykład: w poniższym przypadku kupujący będzie miał nazwę:

„BillComp, Name1 Surname1”

natomiast odbiorca zostanie zapisany jako:

„ShippComp, Name2 Surname”.

6.4. Domyślny status metod płatności

Po otrzymaniu zamówienia w WooCommerce, w zależności od zastosowanej metody płatności, należy ustawić następujący status:

6.5. Obsługa Irlandii Północnej

Jeżeli sprzedajesz na terenie Irlandii Północnej, należy oznaczyć specjalną nazwę kraju, aby wszystkie zasady związane z OSS (np. oddzielna numeracja) były odpowiednio uwzględniane.

Nadal należy jednak zapewnić prawidłowe stawki podatku w sklepie internetowym.

W wywołaniu API, jako odpowiedź na zapytanie, sklep internetowy musi przekazać jedną z poniższych nazw kraju:

• United Kingdom (UK) - Northern Ireland
• XI

7. Podgląd zamówień

W pierwszej kolejności należy zbudować odpowiedni adres URL do listy zamówień, który ma następującą strukturę:

 [Podstawowy adres URL sklepu internetowego]+ /wp-json/wc/v1/orders?per_page=1&amp;order=desc. Example: https://mystore.com/wp-json/wc/v1/orders?per_page=1&order=desc

Jeżeli sklep internetowy obsługuje HTTPS, należy użyć uwierzytelniania Basic Authentication. W przeciwnym przypadku należy zastosować OAuth.

Poniższe obrazki przedstawiają oba przypadki. Ostatecznie jako wynik powinien zostać zwrócony kod JSON zawierający listę zamówień.

Przydatne linki:

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

8. Aktualizacja stanów magazynowych produktów

Typ: POST

Przykład wywołania:

Call example : http://[moja trgovina]/wp-json/wc/v1/products/batch

Zawartość: (3982 musi być identyfikatorem produktu w sklepie internetowym)

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

Odgovor je izpis podatkov o artiklu, ki vsebuje "stock_quantity" : 15000

9. Podgląd produktów i stanów magazynowych

Typ: POST

Przykład wywołania:

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

Zawartość: Brak (Without) 

Response is the Odgovor je izpis podatkov o artiklu, ki vsebuje "stock_quantity" s ustrezno vrednostjo.

10. Opis najczęstszych błędów 

0.1. Błąd transferu  - Error parse respond 

Error

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"]) 

Ten typ błędu pojawia się w momencie zmiany czasu z czasu letniego (DST) na czas standardowy lub odwrotnie.

Po zmianie zegara na czas letni (DST) należy ustawić strefę czasową na UTC +2 (wcześniej było +1).

Po zmianie zegara na czas standardowy należy ustawić strefę czasową na UTC +1.

10.2. Błąd testu połączenia

W przypadku poprawnego połączenia, po kliknięciu przycisku „Test połączenia” zostanie wyświetlone potwierdzenie.

Natomiast w przypadku wystąpienia problemów lub błędów zaleca się użycie narzędzia/programu do testowania połączenia Postman.

Ponieważ każde ustawienie WooCommerce jest indywidualne dla danego sklepu, mogą wystąpić problemy komunikacyjne pomiędzy MetaKocka a WooCommerce.

W przypadku problemów zalecamy wykonanie wstępnego testu w celu sprawdzenia poprawności konfiguracji interfejsu WooCommerce.

Zalecamy użycie programu Postman.

10.3. Błąd synchronizacji wariantów produktów

Jeżeli w sklepie internetowym występują warianty produktów i chcesz przesłać wszystkie warianty ze sklepu do MetaKocka, może pojawić się następujący błąd.

W takim przypadku należy włączyć wersję API v1 w sekcji „Ustawienia dodatkowe”.

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"])