Woocommerce - integracija s MetaKockom

1.  Uspostava veze za razmjenu

       1.1 Uspostava veze s online trgovinom - Woocommerce

       1.2. Uspostava veze u MetaKocki


2. Sinkronizacija proizvoda

        2.1. Varijacija proizvoda

        2.2. Dodatni opisi proizvoda


3. Postavke prefiksa za narudžbe


4. Podrška za Up-sell 


5. Određivanje Lot brojeva


6. Dodatne mogućnosti prijenosa narudžbi iz online trgovine u MK

       6.1. Preslikavanje specifičnih polja države

       6.2. Preslikavanje poreznog broja firme

       6.3. Dodatni parametri pri imenu kupca /primatelja

       6.4. Podrazumijevani statusi platnih instrumenata

       6.5. Podrška za Severnu Irsku


7. Pregled narudžbi- za programere


8. Ažuriranje zaliha proizvoda- za programere 


9. Pregled proizvoda - za programere


10. Opis čestih pogreški

    10.1. Pogreška pri prijenosu

    10.2. Pogreška pri testiranju veze

    10.3. Pogreška sinkronizacije proizvoda sa varijacijama




1. Uspostava veze za razmjenu/sinkronizaciju


Integracija online trgovine postavljene na Woocommerce platformi pomoću MetaKocke omogućava: 

- automatske prijenose narudžbi sa svim podacima kupca (primatelj, platitelj, vrsta plaćanja, popusti i naručeni proizvodi)

- sinkronizaciju proizvoda (proizvodi se mogu prenijeti iz online trgovine u MetaKocku sa svim podacima koje ste već unijeli u online trgovini ukoliko proizvodi imaju upisan SKU kod) 

- automatsku sinkronizaciju zaliha iz MetaKocke u online trgovinu. Prije svega je potrebno imati uređene zalihe u online trgovini.


Računi koji se bez dodatnog rada generiraju na temelju automatsko prenesenih narudžbi se za zakonski određena platna sredstva takođe fiskalno provjeravaju u FURS-u, dok se u skladu s tim za izdanu robu snižavaju zalihe robe i osvježuju zalihe u online trgovini (ako je tako podešeno). 


1.1 Za uspostavljanje veze sa Woocommerce trgovinom potrebno je iz Woocommerce trgovine pribaviti sljedeće podatke: 



Postupak pribavljanja tih podataka je prikazan u nastavku, 





!!U novijim verzijama WC je postupak nešto drugačiji pri generiranju API ključa 



Gornje podatke kopirajte pošto će Vam biti potrebne prilikom dodavanja veze u MetaKocki


1.2. Nakon prijave u MetaKocku u Postavkama/ Linkovi dodajte novu vezu kao što je prikazano da slici ispod:





U slučaju uspješne veze ćete klikom na gumb ''Test veze'' dobiti potvrdu; u slučaju da postoje problemi/pogreške možete se poslužiti alatom/ programa za testiranje veze Postman..

Pošto je svaka postavka WC posebna za sebe , može doći to problema pri komunikaciji između MetaKocke i WC. U tom slučaju preporučuje se početno testiranje ispravnosti postavke sučelja. Preporučujemo upotrebu programa Postman.



Napravi dokument: Označite u što želite da Vam se narudžbe prenose iz online trgovine 



Po uključivanju funkcije "Automatski prijenos narudžba" narudžbe će se početi prenositi u MetaKocku.



U slučaju da želite da se narudžbi promijeni status i u online trgovini, kada je narudžba otpremljena (važi pri upotrebi Order Management modula) odaberite opciju ''Otpremljene pakete automatski označi kao poslane u online trgovini'' i spremite promjenu. 


!!Kada su online trgovina i proizvodi povezani, potrebno je podesiti i odgovarajuće dodatne postavke, prije svega način za prijenos

uplata i određivanje dostavne službe!!



U slučaju uključivanja "Skladišta za sinkronizaciju zaliha" izvodiće se automatska sinkronizacija zaliha u svim online trgovinama na svakih 5 minuta, u kojim MetaKocka provjeri, ukoliko su se izmjenile zalihe sinkroniziranih proizvoda. Kod onih gdje je došlo do izmjene, podaci će se poslati u online trgovinu.


2. Sinkronizacija proizvoda (online trgovina > MetaKocka)


Proizvode prenosite iz online trgovine u MetaKocku. Za prijenos proizvoda i narudžbi proizvodi obavezno moraju imati jedinstvene SKU kodove u online trgovini.


U slučaju da imate mnogo proizvoda sa neodređenim SKU kodovima, u WooCommerce trgovini to možete urediti s pluginom Sku Regenerator (ili sličnim), koji omogućava određivanje SKU kodova/prepis kodova,..




2.1 Varijacije proizvoda (npr. boje, veličine, dužine


Ako u online trgovini prodajete proizvode, koji imaju varijacije (npr. boje, veličine), potrebno je svakom proizvodu odrediti SKU kod, koji će onda biti ista šifra proizvoda u MetaKocki. Primjer je prikazan na slikama ispod. U tom slučaju će se narudžba varijacije proizvoda preslikati u MetaKocka proizvod.


























Ukoliko proizvodi imaju varijacije i želite sve proizvode iz online trgovine prenijeti u MK, možete dobiti donju pogrešku. U tom slučaju potrebno je u ''Dodatnim postavkama'' uključiti verziju v1 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 proizvoda

Ukoliko želite iz online trgovine prenijeti dodatne opise za popis proizvoda, to bi bilo jedino moguće putem meta_data oznak preko rezultata REST orders poziva. 


Funkcionalnost je potrebno dodatno uključiti u postavkama - https://metakocka.freshdesk.com/a/solutions/articles/3000077086


Npr. željeli biste proizvodu "Torbica'' dodati još dva opisa:


U tom slučaju je na MK sučelju za online trgovine potrebno uključiti dodatnu mogućnost "productExtraDescription" (kontaktirajte podršku kako bi Vam uključili), JSON struktura odgovora REST order poziva koja mora sadržavati podatke kao dodatne vrijednosti u meta_data. 






3. Postavke prefiksa za narudžbe 


U slučaju da imate više online trgovina, način podešavanja prefiksa prije pojedinačne narudžbe možete pogledati u članku https://www.tychesoftwares.com/how-to-add-prefix-or-suffix-to-woocommerce-order-number/

V JSON konstrukciji narudžbe postoje dva polja za oznaku narudžbe :

  • "Id" - broj, koji interno koristimo za utvrđivanje dupliciranih narudžbi odnosno izmjenu podataka narudžbe u WC trgovini
  • "number" - oznaka, koja se prikazuje na svim mjestima u MetaKocki odnosno Order Management. 

"Id" se nikad ne mijenja, pošto se sam povećava. S druge strane, ''number'' možete proizvoljno izmijeniti (npr. iz "1001" u "SLO-1001") i neće doći do dupliciranja narudžbi. Jedino ograničenje je, da to važi za online trgovine koje su u MK dodane od 1.1.2018 pa nadalje. Ukoliko je trgovina bila dodana prije tog datuma, potrebno je upitati na MK podršci, da provjere stanje preko parametra "useInternalIdForOrderId".




4. Podrška za up-sell


Ukoliko pri kupovini, stranki omogućite izvođenje up-sell proizvoda, potrebno je pobrinuti se za sljedeće: 

  • up-sell mora biti vremenski ograničen - recimo 12 sati. Narudžba u tom razdoblju ne sme biti otpremljena, zato što mora sačekati na eventualni up-sell. 
  • narudžba ne smije dobiti status ''processing'' jer će onda preći u otpremanje. Mora imati neki od prijelaznih statusa  (npr. "waiting-upsell") pa je samim tim potrebno od strane WC osigurati (razviti funkcionalnost), promjenu statusa u ''processing'' nakon određenog vremena.
  • u slučaju promjene statusa se obavezno mora izvesti i update preko webhook


5. Određivanje Lot brojeva

 

U slučaju, da za proizvod vodite lot brojeve u MetaKocki (npr. prodaja namernica) i da online trgovine ne sadržava podršku za unos lot brojeva, MetaKocka će automatski odrediti Lot broj pri prijenosu narudžbe. Postupak je sljedećI:

  • Lot številka se automatski odredi samo u slučaju prijenosa na račun,
  • proizvod na kom se vode lot brojevi mora biti označen
  • računu se automatski odredi skladište prema postavkama firme,
  • za proizvod s lot brojem se na skladištu računa provjeri ukoliko postoje zalihe. Ako postoje, odabere se lot broj s najvećom količinom na lageru

Ako se proizvodu ne odredi lot broj, prilikom prijenosa narudžbe će biti prikazana greška i narudžba se neće prenijeti. Primjer pogreške: 3952 - Janez Novak : Proizvod 56 -m2 - Mast od divljeg kestena 100ml mora imati određeni Lot 




6. Dodatne mogućnosti prenosa narudžbi iz online trgovine u MetaKocku


6.1. Preslikavanje specifičnih polja države


U određenim državama su važne dodatne oznake u adresama (naročito pokrajine) i s tim u vezi su ispod napisana pravila na koji način adresa mora biti zapisana u WC, kako bi se pravilno preslikala u MK adrese.


Država
Oznaka u adresiOčekivan podatak u JSON
RomunijaJudet{billing / shipping}.state

Localitate{billing / shipping}.city
ItalijaProvince code{billing / shipping}.state


Preslikavanje Rumunjska polja za upotrebu u programu Urednik adresa

Za potrebe provjeravanja pravilnih adresa u aplikaciji Urednik adresa, potrebno je podatke o adresama navesti na poseban način. Ispod je primjer JSON zahtjeva od strane WC (sadrži samo polja, koja su bitna). Imena polja moraju biti točno jednaka kao u donjem primjeru i točno kao metapodaci dokumenta (ne npr. partnera, proizvoda itd). Za donji zahtjev će se tako za kupca podesiti naslov "Ulica 1, BL:12 SC:D ET:4 AP:17" odnosno za primatelja "Ulica 2, BL:12_2 SC:D_2 ET:4_2 AP:17_2" . 


WC ima više različitih verzija API sučelja (trenutno je posljednja v3). Podrazumijevani MK koristi sučelje v1. Ako Vam programeri nadograde verziju WC, upozorite ih na sljedeće:

  • neka nadograde na verziju V1
  • mogu nadograditi na verziju V3, ali se u Dodatnim postavkama za tu online trgovinu mora uključiti "API verzija" - "V2"

Napomena : dopunu je potrebno pripremiti na sljedećim djelovima WC sučelja:

  • aktiviranje webhook poziva MK (tada se šalje cjelokupni JSON narudžbe)
  • vraćanje narudžbi preko API poziva/orders


U polje "address_2" potrebno je navesti još broj ulice. To ćete uraditi na sljedeći način: 

  • u WC trgovini potrebno je na odgovarajući način odvojiti korisničko sučelje, kako bi korisnik odvojeno unio ulicu i kućni broj
  • kućni broj mora biti upisan u polje "address_2" od partnera / primatelja u JSON WC odgovoru,
  • u MK je potrebno na svakoj RO trgovini uključiti opciju "Združi podatke iz adresa u jednu adresu" - više

[{    "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"      }    ]  }]
JavaScript

6.2. Preslikavanje poreznog broja firme


Ukoliko u online trgovini omogućite i firmama izdavanje računa, posljedično ćete imati slobodno polje za unos poreznog broja; te podatke možete iz online trgovine prenijeti u MK preko JSON ''meta_data'' podataka. Važe sljedeća pravila: 

  • buyer_tax_id / receiver_tax_id - porezni broj kupca odnosno primatelja. Ako je vrijednost navedena, onda partner automatski u MK postane ''firma'' i ''porezni obveznik''. 
  • buyer_tax_payer / receiver_tax_payer - ako sadrži vrijednost ''false'', onda se u MK firma označuje kao neobveznik. Kako nalaže gornja točka - ako vrijednost nije navedena, onda se firma automatski označuje kao porezni obveznik.

Napomena: dopunu je potrebno pripremiti na sljedećim djelovima WC sučelja:

  • aktiviranje webhook poziva MK (tada se šalje cjelokupni JSON narudžbe)
  • vraćanje narudžbi preko API poziva/orders


Napomena: podrazumijevani MK koristi V1 REST sučelje. Ukoliko ćete oznake dodati samo u V2 sučelje, potrebno je izmijeniti postavke u ''Dodatne postavke'' -> ''Online trgovine'' , odaberite trgovinu i potom potražite "Verzija API" i podesite na "V2".


[{

        "id": 24777,

        "parent_id": 0,

        "status": "completed",

        "order_key": "wc_order_5b1e09c34a158",

        "number": "25386",

        ...........

        "billing": {

            ...........

            "first_name": "Gabriela",

            "last_name": "Birz",

            "country": "RO",

        },

        "shipping": {

            .............

            "first_name": "Gabriela",

            "last_name": "Birz",

        },

        .............

        "meta_data": [{

                "key": "buyer_tax_id",

                "value": "SI100200300"

            }, {

                "key": "buyer_tax_payer",

                "value": "true"

            }, {

                "key": "receiver_tax_id",

                "value": "SI100200300"

            }, {

                "key": "receiver_tax_payer",

                "value": "false"

            }

        ]

    }

}]


6.3. Dodatni parametri pri imenu kupca /primatelja


Ukoliko se u metapodacima narudžbe nalazi podatak "_billing_comp"  ili "_shipping_comp" , samo taj naziv će biti zapisan pod imenom kupca. Npr. za donji primjer će kupac imati ime "BillComp, Name1 Surname1" , dok će primatelj biti "ShippComp, Name2 Surname". 




6.4. Podrazumijevani statusi platnih instrumenata


Kada u WooC stigne narudžba, na temelju različitih platnih instrumenata podešavaju se sljedeći statusi:


OznakaPlatni instrumentPočetni status
paypalPayPalPending - narudžba izvedena, ali još nije plaćena
Processing - plaćanje je izvršeno
bacsDirect bank transferOn hold
chequeCheck paymentsOn hold
codCash on deliveryProcessing


6.5. Podrška za Severnu Irsku

Ukoliko prodajete na prostoru Severne Irske, potrebno je navesti posebnu oznaku za državu, kako bi se uzimala u obzir sva pravila koja se vezuju za OSS (npr. odvojeno numeriranje). Potrebno je još uvijek osigurati pravilne porezne stope u trgovini. Online trgovina mora u API pozivu pri odgovoru na zahtjev pružiti jedan od donjih naziva za državu. 

  • Ujedinjeno Kraljevstvo (UK) - Severna Irska
  • United Kingdom - Northern Ireland
  • XI


7. Pregled narudžbi


Prije svega moramo izgraditi odgovarajuću URL adresu za popis narudžbi, koja ima oblik [osnovni URL online trgovine] + /wp-json/wc/v1/orders?per_page=1&order=desc. Primjer : https://mystore.com/wp-json/wc/v1/orders?per_page=1&order=desc


Ukoliko online trgovina podržava HTTPS, koristimo Basic authentication. U protivnom se koristi OAuth. Slike ispod prikazuju oba primjera. Na kraju kao rezultat će izaći JSON sa narudžbama.


Korisni linkovi:





8. Ažuriranje zaliha proizvoda


Tip : POST

Primjer poziva : http://[moja trgovina]/wp-json/wc/v1/products/batch

Sadržaj (3982 mora biti id proizvoda u online trgovini) :


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


Odgovor je ispis podataka o proizvodu , koji sadrži "stock_quantity" : 15000


9. Pregled proizvoda i njegovih zaliha

Tip : POST

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

Sadržaj : bez


Odgovor je ispis podataka o proizvodu, koji sadrži "stock_quantity" sa odgovarajućom vrijednošću




10.  Opis čestih pogreški


10.1. Pogreška pri prijenosu - Error parse respond 


Pogreška:

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


Pogreška se pojavljuje, kada se računanje vremena mijenja iz zimskog u ljetnje ili obrnuto.


Kada se računanje vremena promijeni u ljetnje, potrebno je u Woocommerce-u pomaknuti vrijeme na UTD +2 (prije je bilo UTD +1). 


Kada se računanje vremena promijeni u zimsko, potrebno je u Woocommerce-u pomaknuti vrijeme na UTD +1 (prije je bilo UTD +2) 



10.2.  Pogreška pri testu veze

.

U slučaju uspješne veze ćete klikom na gumb ''Test veze'' dobiti potvrdu; u slučaju da postoje problemi/pogreške možete se poslužiti alatom programa za testiranje veze Postman.. Pošto je svaka postavka WC posebna za sebe može doći do problema pri komunikaciji između MetaKocke i WC. U tom slučaju preporučuje se početno testiranje ispravnosti postavke sučelja. Preporučujemo upotrebu programa Postman. 


10.3 Pogreška sinkronizacije proizvoda s varijacijama


Ukoliko proizvodi imaju varijacije i želite sve proizvode iz online trgovine prenijeti u MK, možete dobiti sljedeću pogrešku. U tom slučaju potrebno je u ''Dodatnim postavkama'' uključiti verziju v1 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"])