1. Integration Woocommerce <> MetaKocka

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

- automated transfers of orders with all customer data (recipient, payer, type of payment, discounts, and ordered items)

- product synchronization (products can be transferred from the online store to MetaKocka with all the data you have already entered in the online store if they have SKU code inserted)

-automated stock synchronization from MetaKocka to the online store. However, first of all, it is important to have the stocks arranged in the online store.

Invoices that are generated without additional work based on automatically transferred orders are also verified at FURS for legally defined means of payment, and for issued goods, the stock of goods is correspondingly reduced and refreshed in the online store as well (if so set).

1.1 To establish a connection with the Woocommerce store, it is necessary to obtain the following information from the Woocommerce store:

• Webstore URL address (like... "www.mystore.com")
• Consumer Key
• Consumer Secret

The steps needed to obtain such data are shown below:

In newer versions of WC, the procedure of generating API key is somewhat different!

Copy the data from above - you will need it when adding the connection to MetaKocka.

1.2. After logging in to MetaKock, in Settings/Links, add a new connection as shown in the image below:

Choose "Woocommerce" and click "Add"

Paste data from Woocommerce - Customer key and secret, URL, and Save. Click on Test connection - you should get confirmation that integration has been successful. 

For the Order management module choose Sales Orders, but if you need just invoice creation choose invoice

Check  "Automatic order transfer" if you want all orders received in Woocommerce to be transferred to MetaKocka, but if manual editing in Woocommerce is needed leave it unchecked.

If the manual transfer is needed - choose how many days back orders should be collected and click on Import orders. 

2. Product synchronization (Woocommerce > MetaKocka)

You can transfer products from the online store to MetaKocka automatically. To transfer products and orders, products in the online store must have unique SKU codes.

In case of having a lot of products with unassigned SKU codes, that is possible to arrange in the Woocommerce store with the SKU Regenerator plugin, which enables the assignment of SKU codes/copying codes. 

2.1 Product variation (ex. color, size, length) 

If in the online store, you are selling product variants (different colors, sizes, etc) it is necessary to assign an SKU code to each product, which will be equal to the product code in MetaKocka. An example is shown in the pictures below. In such a case, the order of product variants will be copied accordingly to the MetaKocka product. 

In case of willing to transfer all product variants from the online store to MK, you may receive the following error. In such a case, it is necessary to enable the v1 API version in ''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  Additional product description

In case you are willing to transfer additional descriptions to the product from the online store, it is possible to do it via meta_data oznak over the results of the REST orders call. 

It is needed to additionally activate functionality in settings -  https://metakocka.freshdesk.com/a/solutions/articles/3000077086

Ex. Under the product ''Torbica'' we would like to add two more descriptions:

In such a case, you need to activate the additional option "productExtraDescription" on MK interface (you can contact customer service for additional help), JSON structure answer to REST order call must contain data as additional values in meta_data: 

3. Prefix setting for orders

In case of having more online stores, you can check the method of setting a prefix before the individual order in the following article:  https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/

In JSON construction of the order, there are two fields for denoting an order:

• "Id" - number, that we use internally to determine double orders or change order data in the WC store
• "number" - label, which is shown on all the places in MetaKocka or Order Management 

"Id" is never changed, because it can only increase. On the other hand, ''number'' can be changed arbitrarily (ex. from "1001" to "SLO-1001") and there will be no double orders created whatsoever. The only limit is that this is valid for online stores that have been added to MK from 1.1.2018 onwards. In case of adding the store before this date, you need to contact MK support, to check the status via the parameter "useInternalIdForOrderId". 

4. Up-Sell support

If you offer Up-Sell to a customer when purchasing the product, it is important to ensure the following: V kolikor ob nakupu stranki omogočate izvedbo upsell artikla, je potrebno zagotoviti naslednje :

• up-sell needs to be time-limited - for instance 12 hours. In between, the order cannot be dispatched, as it needs to await for a possibility of up-sell 
• order must not receive status ''processing'', since that would directly lead to ''dispatched'' status. It needs to have any kind of transitional status assigned (ex. ''waiting-upsell'') to ensure that changing the status to ''processing'' will be possible in a certain period of time 
• in case of changing the status, performing an update via webhook is mandatory

5. Determining Lot numbers

In the case of recording lot numbers in MetaKocka (ex. selling groceries) with the online store not being supported for lot number entry, MetaKocka will automatically assign lot numbers when transferring orders. The procedure is the following:

• The lot number is automatically assigned only in case of transfer to the invoice
• Product must be artikel mora biti označen, da se na njem vodijo Lot številke,
• The invoice has a warehouse automatically assigned according to the company settings
• In the warehouse of invoices, for the product with lot number, it is checked whether any stock exists. If it does, a lot number with the biggest quantity in the warehouse is chosen

If the product has no lot number assigned, there will be an error shown when transferring the orders meaning that the order will not be transferred. Example of error: 3952 - Janez Novak: Product 56 - m2 - Wild chestnut ointment 100 ml must have a lot number assigned. 

6. Additional possibilities for transferring orders from the online store to MetaKocka

6.1. Mapping specific fields for country

In certain countries, additional labels in addresses (mainly provinces) are important, therefore below are the rules for writing addresses in WC in order to correctly copy them to MK addresses.

Mapping Romania fields for usage in the Address Editor program

To check correct addresses in the Address Editor application, addresses need to be transmitted in a specific way. Below is an example of a JSON request from WC (containing only important fields). Names of the fields need to be completely equal to the ones in the example below and the same as the metadata of the document (not of the partner, products, etc.). For the request below, the buyer's address would be set as  "Street 1, BL:12 SC:D ET:4 AP:17" or for the receiver "Street 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2".

WC has different versions of the API interface (currently, the latest one is v3). MK works on the v1 interface by default. If developers would upgrade your WC interface, they need to consider this :

• upgrading to interface version V1 normally
• upgrading to version V3 but, under Additional Settings for such online store ''API version'' - ''V2'' needs to be turned on.

Note: supplement needs to be prepared on the following parts of the WC interface:

• activating webhook and call MK (whole JSON of order is sent)
• returning orders via API call/orders

In the field "address_2" the house number needs to be added. You can do it in the following way:

• in the WC store, you need to separate the user's interface accordingly so that the user can separately enter the street and house number
• house number needs to be entered in the field "address_2" of partner/receiver in JSON WC response,
• in MK, on each RO store, you need to turn on the option ''Group data from addresses as one address' - more.
  
  

[{    "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 company's tax number

In case of enabling the issue of invoices to the companies as well, consequently adding the field for entering the tax number, you can easily transfer such data to MK through JSON "meta_data". The following rules apply: :

• buyer_tax_id / receiver_tax_id - tax number for the buyer (i.e. receiver). If the value is given, the partner automatically becomes a ''company'' and ''taxpayer''. 
• buyer_tax_payer / receiver_tax_payer - if it contains the value "false", then in MK, a company is denoted as non-taxpayer. As the prior point suggests - if the value is not given, then the company is automatically denoted as a taxpayer 

Note: supplement needs to be prepared on the following parts of the WC interface:

• activating webhook and call MK (whole JSON of order is sent)
• returning orders via API call/orders

Note: MK uses the V1 REST interface by default. In case of adding labels only to the v2 interface, you would need to change the settings under ''Additional settings'' -> ''Online stores'', choose the store, and search for ''API Version'' which you need to set on ''V2'.

6.3. Additional parameters in the name of the buyer/receiver 

In case of finding "_billing_comp" or "_shipping_comp" inside metadata, only that notion will be written before the buyer's name. For instance, in the example down below, the buyer will be named "BillComp, Name1 Surname1", while the receiver on the other side will be named "ShippComp, Name2 Surname".

6.4. Default status of payment instruments 

When you receive an order in WooC, according to different payment instruments, the following status needs to be set:

6.5. Northern Ireland support

If you are selling on the territory of Northern Ireland, you need to denote the special label for this country, so that all the rules connected to OSS (such as separated numeration) would be considered. You would still need to ensure the correct tax rates in your store. In the API call, as the response to the request, the online store needs to provide one of the following names for the country. 

• United Kingdom (UK) - Northern Ireland
• XI

7. Order overview

Firstly, we need to build an appropriate URL address for the list of orders, which has the shape of [basic URL of the online store] + /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

If the online store supports HTTPS, we should use Basic Authentication. Otherwise, OAuth is used. The pictures below show both cases. In the end, as a result, there needs to be JSON with orders shown. 

Useful links :

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

8. Updating product stock

Type: POST

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

Content: (3982 has to be product ID in the online store) 

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

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

9. Product and stock overview 

Type: POST

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

Content: Without

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

10.  Description of frequent errors

10.1. Transfer error - 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"]) 

This type of error appears when the clock is changed from Daylight saving time (DST) to Standard Time or vice-versa. 

When the clock is changed to Daylight saving time (DST), you would need to change the time to UTD +2 (before it was +1).

When the clock is changed to Standard Time, you would need to change the time to UTD +1 (before it was +1).

10.2.  Test connection error

In case of a successful connection, after clicking on the button ''Connection test'' you will receive a confirmation. On the other hand, in case of any problems/errors, do not hesitate to use tools/program for testing the connection Postman.

Since each WC setting is valid solely for itself, you may experience communication issues between MetaKocka and WC. In case of a problem, we recommend performing an initial test to check the validity of interface adjustment on the WC. We kindly recommend using the Postman program.

10.3 Product variant synchronization error 

If there are product variants and you are willing to transfer all of them from the online store to MK, you may encounter the following error. In such a case, you need to turn on the v1 version of API in ''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"])