1.  Vzpostavitev povezave za izmenjavo

       1.1 Vzpostavitev povezave s spletno trgovino - Woocommerce

       1.2. Vzpostavitev povezave v MetaKocki

2. Sinhronizacija artiklov

        2.1. Variacija artiklov

        2.2. Dodatni opisi artikla

        2.3. Sinhronizacija cen

3. Nastavitev predpone za naročila 

4. Podpora za Up-sell 

5. Določanje Lot števil

6. Dodatne možnosti prenosa naročil iz spletne trgovine v MK

       6.1. Preslikava specifičnih polj države

       6.2. Preslikava davčne številke podjetja

       6.3. Dodatni parametri ob kupcu/prejemniku 

       6.4. Privzeti statusi plačilnih inštrumentov

       6.5. Podpora za Severno Irsko

7. Pregled naročil - za razvijalce

8. posodobite zaloge artikla - za razvijalce

9. Pregled artikla - za razvijalce

10. Opis pogostih napak

    10.1. Napaka pri prenosu

    10.2. Napaka pri test povezavi

    10.3. Napaka sinhronizacije artiklov z variacijami

1. Vzpostavitev povezave za izmenjavo / sinhronizacijo

Integracija spletne trgovine postavljeni na Woocommerce platformi z MetaKocko omogoča:

- avtomatske prenose naročil z vsemi podatki kupca ( prejemnik, plačnik, vrsto plačila, popusti in naročenimi artikli) 

- sinhronizacijo artiklov ( artikle se lahko iz spletne trgovine prenese v MetaKocko z vsemi podatki, ki ste jih že vnesli v spletni trgovini v kolikor imajo ti vpisano SKU kodo)

- avtomatsko sinhronizacijo zalog iz Metakocke v spletno trgovino. Pomembno je, da imate najprej urejeno zalogo v spletni trgovini

Računi, ki se brez dodatnega dela generirajo na podlagi avtomatsko prenešenih naročil se za zakonsko določena plačilna sredstva tudi potrdijo na FURS-u, za izdano blago pa se ustrezno zniža zaloga blaga in osveži zalogo tudi v spletni trgovini ( če je tako nastavljeno).

1.1 Za vzpostavitev povezave z Woocommerce trgovino je potrebno iz Woocommerce trgovine       pridobiti naslednje podatke :

• spletni naslov trgovine (npr. "www.mojatrgovina.si")
• Consumer Key
• Consumer Secret

Postopek pridobivanja teh podatkov je prikazan v nadaljevanju,  

!!V novejših verzijah WC je postopek korakov do generiranje API ključa nekoliko drugačen.!!

Zgornje podatke kopirajte saj jih boste potrebovali pri dodajanju povezave v MetaKocki,

1.2. Po prijavi v MetaKocko v Nastavitve/ Povezave dodajte novo povezavo kot prikazano na spodnji sliki:

V primeru uspešne povezave boste po kliku na gumb "Test povezave" dobili potrditev, v primeru da bi bile težave/napake pa se lahko poslužite orodja/programa za testiranje povezave Postman..

Ker je vsaka postavitev WC svoja ločena postavitev, lahko pride do težav pri komunikaciji med MetaKocka in WC. V primeru težave je dobro na začetku testirati, ali je vmesnik na WC pravilno nastavljen. Priporočamo uporabo programa Postman.

Izdelaj dokument: Označite v kaj želite da se vam naročila prenašajo iz spletne trgovine

Po vklopu funkcije "Samodejni prenos naročil" se bodo naročila pričela prenašati v MetaKocko.

V primeru, da želite da se status naročilu spremeni tudi v spletni trgovini, ko je naročilo odpremljeno ( velja ob uporabi Order management modula) izberite opcijo "Odpremljene pakete samodejno označi kot poslano v spletni trgovini" in shranite spremembo

!!Ko je spletna trgovina povezana in so artikli povezani, je potrebno nastaviti še ustrezne dodatne nastavitve, predvsem pa kako se prenesejo plačila in določi dostavne službe!!

V primeru vključitve "Skladišče za sinhronizacijo zaloge" se bo izvajala avtomatična sinhronizacija zaloge v vse spletne trgovine vsakih 5 minut, ko MetaKocka preveri, če se je spremenila zaloga sinhroniziranih artiklov. Pri tistih, kjer je prišlo do spremembe, se podatki pošljejo v spletno trgovino.

2. Sinhronizacija artiklov (spletna trgovina > MetaKocka)

Artikle  prenesete iz spletne trgovine v MetaKocko. Za prenos artiklov in naročil je obvezno, da imajo artikli v spletni trgovini unikatne Sku kode.

V primeru, da teh nimate določenih in imate veliko artiklov je možno to v Woocommerce trgovini urediti z pluginom Sku Regenerator ( ali podobnim), ki omogoča določanje SKU kod/ prepis kod,..

2.1 Variacije artiklov ( npr barve, velikosti, dolžina) 

Če v spletni trgovini prodajate artikle, ki imajo variacije ( npr barve, velikosti), je potrebno vsakemu artiklu določiti SKU kodo, ki bo potem enaka šifri artikla v MetaKocki. Primer je prikazan na spodnjih slikah. V tem primeru se bo naročilo variacije artikla ustrezno preslikalo v MetaKocka artikel.

V koliko imajo artikle variacije in želite vse artikle iz spletne trgovine prenesti v MK, lahko dobite spodnjo napako. V tem primeru je potrebno v "Dodatne nastavitve" vključiti v1 verzijo API-ja.

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  Dodatni opisi artikla

V kolikor želite iz spletne trgovine prenesti dodatne opise k izpisu artikla, je le to mogoče preko meta_data oznak preko rezultata REST orders klica. 

Funkcionalnost je potrebno dodatno vključiti v nastavitvah - https://metakocka.freshdesk.com/a/solutions/articles/3000077086

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

V tem primeru je potrebno na MK vmesniku za spletne trgovine vključiti dodatne možnost "productExtraDescription" (pokličite na podporo, da vam vključimo), JSON struktura odgovora REST order klica pa mora vsebovati podatke kot dodatne vrednosti v meta_data :

2.3 Sinhronizacija cen

Sinhronizacija cen poteka iz Metakocke v Woocommerce. Nastavite cenik iz katerega se bodo cene sinhronizirale in sprožite sinhronizacijo cen.

3. Nastavitev predpone za naročila

V primeru, da imate več spletnih trgovin, si lahko način nastavitve predpone pred posamezno naročilo ogledate v članku https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/

V JSON zgradbi naročila obstajata dva polja za oznako naročila :

• "Id" - številka, ki jo interno uporabimo za ugotavljanje podvojenih naročil oz. spreminjanje podatkov naročila v WC trgovini
• "number" - oznaka, ki se prikazuje na vseh mestih v MetaKocka oz. Order Management.

"Id" se nikoli ne spreminja, saj se samo povečuje. Na drugi strani pa "number" lahko poljubno spremenite (npr. iz "1001" v "SLO-1001") in ne bo prišlo do podvajanja naročil. Edina omejitev je, da to velja za spletne trgovine, ki so bile v MK dodane od 1.1.2018 naprej. V kolikor je bila trgovina dodana že pred tem, je potrebno povprašati na MK podpori, da preverijo stanje preko parametra "useInternalIdForOrderId". 

4. Podpora za up-sell

V kolikor ob nakupu stranki omogočate izvedbo upsell artikla, je potrebno zagotoviti naslednje :

• up-sell mora biti časovno omejen - recimo 12 ur. Vmes le tega naročila ne smete odpremiti, ker mora počakati na možnost upsell. 
• naročilo ne sme dobiti statusa "processing", ker bo potem odšel v odpremo. Mora imeti nek vmesni status (npr. "waiting-upsell") in potrebno je na strani WC zagotoviti (razviti funkcionalnost), da bo spremenila status naročila v "processing" po določenem času. 
• nujno se mora v primeru spremembe statusa izvesti tudi update preko webhook. 

5. Določanje Lot številk

V primeru, da za artikel vodite lot številke v MetaKocki (npr. prodaja živil) in da spletna trgovine ne vsebuje podpore za vnos lot številk, bo MetaKocka avtomatično določila Lot številko ob prenosu naročila. Postopek je naslednji :

• Lot številka se samodejno določijo samo v primeru prenosa na račun,
• artikel mora biti označen, da se na njem vodijo Lot številke,
• računu se samodejno določi skladišče glede na nastavitve podjetja,
• za artikel z lot številko se na skladišču računa preveri, ali obstaja zaloga. Če obstaja, se izbere lot številka z največjo količino na skladišču.

Če se artiklu ne določi lot številka, se bo ob prenosu naročil izpisala napaka in naročilo se ne bo preneslo. Primer napake : 3952 - Janez Novak : Artikel 56 - m2 - Divji kostanj mazilo 100 ml mora imeti določen Lot

6. Dodatne možnosti prenosa naročil iz spletne trgovine v MetaKocko

6.1. Preslikava specifičnih polj države

V določenih državah so pomembne dodatne oznake v naslovih (predvsem province), zato so spodaj vpisane pravila, kako mora biti naslov zapisan v WC, da se pravilno preslika v MK naslove. 

Preslikava Romunija polj za uporabo v programu Urejevalnik naslovov

Za potrebe preverjanja pravilnih naslovov v aplikaciji Urejevalnik naslovov, je potrebno podatke o naslovi sporočiti na posebni način. Spodaj je primer JSON zahtevka iz strani WC (vsebuje samo polja, ki so pomembna). Imena polj morajo biti točna enaka kot v spodnjem primeru in točno kot metapodatki dokumenta (ne recimo partnerja, artikla, itd). Za spodnji zahtevek se bo tako za kupca nastavil naslov "Ulica 1, BL:12 SC:D ET:4 AP:17" oz. za prejemnika "Ulica 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2".

WC ima več različnih verzij API vmesnika (trenutno je zadnja v3). MK po privzeto deluje na vmesniku v1. Če vam programerji naredijo nadgradnjo na WC, jih opozorite naslednje :

• naj naredijo nadgradnjo na verzijo V1,
• lahko naredijo nadgradnjo na verziji V3, vendar se mora pod pod Dodatne nastavitve za to spletno trgovino vključiti "API verzija" - "V2". 

Opozorilo : dopolnitev je potrebno pripraviti na naslednjih delih WC vmesnika :

• proženje webhook in klicu MK (takrat se pošlje celotni JSON naročila)
• vračanje naročil preko API klica /orders

V polje "address_2" je potrebno podati še številko ulice. To naredite na naslednji način :

• v WC trgovini je potrebno ustrezno ločiti uporabniški vmesnik, da uporabnik ločeno vnese ulico in hišno številko,
• hišna številke mora biti vpisana v polje "address_2" od partnerja / prejemnika v JSON WC odgovoru,
• v MK je potrebno na vsaki RO trgovini vključiti možnost "Združi podatke iz naslovov kot en naslov" - več
  
  

[{
    "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. Preslikava davčne številke podjetja

V kolikor v spletni trgovini omogočate izdajo računov tudi podjetjem in posledično imate polje za vnos davčne številke, lahko iz spletne trgovine te podatke prenesete v MK preko JSON "meta_data" podatkov. Veljajo naslednja pravila :

• buyer_tax_id / receiver_tax_id - davčna številak za kupca oz. prejemnika. Če je podana vrednost, potem partner avtomatično v MK postane "podjetje" in "davčni zavezanec"
• buyer_tax_payer / receiver_tax_payer - če vsebuje vrednost "false", potem se v MK podjetje označi kot da ni davčni zavezanec. Kot pravi zgodnja točka - če vrednost ni podana, potem se podjetje avtomatično označi kot davčni zavezanec. 

Opozorilo : dopolnitev je potrebno pripraviti na naslednjih delih WC vmesnika :

• proženje webhook in klicu MK (takrat se pošlje celotni JSON naročila)
• vračanje naročil preko API klica /orders

Opozorilo : privzeto MK uporablja V1 REST vmesnik. V kolikor boste oznake dodali samo v V2 vmesnik, je potrebno spremeniti nastavitev pod "Dodatne nastavitve" -> "Spletne trgovine", izberete trgovino in potem poiščete "Verzija API" in nastavite na "V2". 

6.3. Dodatni parametra ob imenu kupca /prejemnika

V kolikor se pod metapodatki naročila nahaja podatek "_billing_comp" ali "_shipping_comp", se bo le ta naziv zapisal pod imenom kupca. Npr. za spodnji primer bo imel kupec ime "BillComp, Name1 Surname1", prejemnik pa "ShippComp, Name2 Surname".

6.4. Privzeti statusi plačilnih inštrumentov

Ko v WooC pride naročilo, se glede na različne plačilne inštrumente nastavi naslednji status :

6.5. Podpora za Severno Irsko

V kolikor prodajate v območje Severne Irske, je potrebno za državo navesti posebno oznako, da se potem upoštevajo vsa pravila, ki se navezujejo na OSS (npr. ločeno številčenje). Pravilne davčne stopnje je še vedno potrebno zagotoviti v trgovini. Spletna trgovina mora v API klicu pri odgovoru zahtevka podatni enega od spodnjih nazivov za državo :

• Združeno kraljestvo (UK) - Severna Irska
• United Kingdom - Northern Ireland
• XI

7. Pregled naročil

Najprej gradimo ustrezni URL naslov za seznam naročil, ki ima obliko [osnovni URL spletne trgovine] + /wp-json/wc/v1/orders?per_page=1&order=desc. Primer : https://mystore.com/wp-json/wc/v1/orders?per_page=1&order=desc

V kolikor spletna trgovina podpora HTTPS, uporabimo Basic authentication. Drugače pa OAuth. Spodnje slike prikazujejo oba primera. Na koncu mora kot rezultat priti JSON s naročili.

Uporabne povezave :

• 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) :

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

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

9. Pregled artikla in njegove zaloge

Tip : POST

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

Vsebina : brez

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

10.  Opis pogostih napak

10.1. Napaka pri prenosu - Error parse respond 

Napako 

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

Napaka se pojavi, ko se spremnja čas iz zimskega v poletni ali obratno

Ko se spremeni v Poletni čas je potrebno v Woocommercu prestavil čas na utd+2 (prej utd+1).

Ko se spremeni čas v zimski je potrebno v Woocommercu prestaviti čas na utd +1 (prej utd +2).

10.2.  Napaka pri test povezavi 

V primeru uspešne povezave boste po kliku na gumb "Test povezave" dobili potrditev, v primeru da bi bile težave/napake pa se lahko poslužite orodja/programa za testiranje povezave Postman..

Ker je vsaka postavitev WC svoja ločena postavitev, lahko pride do težav pri komunikaciji med MetaKocka in WC. V primeru težave je dobro na začetku testirati, ali je vmesnik na WC pravilno nastavljen. Priporočamo uporabo programa Postman.

10.3 Napaka sinhronizacije artiklov z variacijami

V koliko imajo artikle variacije in želite vse artikle iz spletne trgovine prenesti v MK, lahko dobite spodnjo napako. V tem primeru je potrebno v "Dodatne nastavitve" vključiti v1 verzijo API-ja.

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