Upute za API povezivanje

API veza (MPAPI) koristi se za povezivanje vaše trgovine i MALL/MIMOVRSTE partnerskog okruženja, tj. za razmjenu informacija o proizvodima i njihovim varijantama, o postavkama dostave i, ne manje važno, za obradu narudžbi.

API je izgrađen na tzv. REST arhitekturi, koja vam omogućuje pristup podacima i izvođenje operacija na njima, kao što su popisivanje podataka, stvaranje, ažuriranje ili brisanje postojećih objekata (proizvodi, pošiljke itd.).
API koristi sigurnu HTTPS vezu.

Za funkcionalnu vezu potrebno je dobiti jedinstveni ključ od MALL Partnera - client_id, který slouží k autorizaci zasílaných požadavků.

Ovi zahtjevi se šalju https://mpapi.mallgroup.com/ u proizvodnom okruženju, bez obzira na zemlju u kojoj ćete nuditi svoju robu.
Država je identificirana po client_id.

Svi podaci se šalju i vraćaju u JSON formatu i UTF-8 kodiranju. Odgovor na poslani zahtjev uvijek vraća HTTP kod, u odgovarajućim metodama i podatke te eventualno paginaciju.

{ "result": { "code": 200/400/403/404/500, "status": OK/ERROR/LIMITED, "message": dodatna poruka }, "paging": { "pages": broj stranica, "size": broj stavki na stranici, "page": trenutna stranica }, "data": { strukturirani podaci } }

Podrobné informace k HTTP kódům, využití stránkování a zejména předepsané struktuře dat jsou k dispozici v online dokumentacija.

Za bržu implementaciju, dostupno je MPAPI klijent (trenutno samo u PHP-u, podržana je verzija 5.5 i novija). Informacije o preuzimanju i najnovija verzija mogu se pronaći na packagist.org/packages/mallgroup/mpapi-client.

Zapisnik promjena

Online dokumentacija sadrži trenutne informacije. Sve promjene bilježe se u odjeljku Dnevnik promjena, uključujući datum stupanja na snagu.

API arhitektura

MP API se temelji na softverskoj arhitekturi ODMOR i osiguran HTTPS protokol.

API krajnje točke

1. Transparentni proxy

• Za neovisno API testiranje može se koristiti transparentni proxy (modove možete pozvati iz online dokumentacije) Lažni poslužitelj ili Proxy za otklanjanje pogrešaka),
• Zahtjeve za transparentni proxy možete pratiti klikom na poveznicu Inspektor u gornjem izborniku,
• Ako ne koristite transparentni proxy, zahtjeve možete slati izravno na URI krajnje točke u produkcijskom okruženju.

2. Produkcijsko okruženje

• URL produkcijskog API-ja možete pronaći na https://mpapi.mallgroup.com/v1/, URL vrijedi za svaku jezičnu varijantu, ali za svaku zemlju vrijede različiti client_id.

Autorizacija

Svaki zahtjev mora sadržavati autorizacijski ključ (ID klijenta). Ovaj ključ je dostupan partnerima na partnerskom portalu.

Format podataka

Svi podaci su u formatu JSON i kodirano kao UTF-8Vrsta sadržaja može se postaviti kao Vrsta sadržaja: aplikacija/json ili Vrsta sadržaja: aplikacija/json; Skup znakova=UTF-8.

Izlaz

Izlaz je u sljedećoj strukturi:

{ "result": { "code": 200/400/403/404/500, "status": OK/ERROR/LIMITED, "message": dodatne informacije o pogrešci }, "paging": { "pages": broj stranica, "size": broj objekata na stranici, "page": broj trenutne stranice }, "data": { data structure } }

Zahtjevi za brisanje ne vraćaju sadržaj (kod 204).

Proizlaziti

Vraća rezultat HTTP kod, status i bilo koja poruka o pogrešci.

Paginacija

Objekt straničenje koristi se kada je izlaz podijeljen na više stranica.
Straničenje se može postaviti pozivanjem URL-a s parametrima stranica i veličina_straniceZadana veličina stranice (i preporučena maksimalna vrijednost) je 100.

Primjer:
https://mpapi.mallgroup.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}

Podaci

Struktura podataka varira ovisno o krajnjoj točki i opisana je za svaku krajnju točku zasebno u online dokumentacija.

HTTP statusni kodovi

• 200 mesh – vše je v pořádku, data jsou vrácena správně,
• 201 Kreirano – odeslaná data byla přijata a entita byla vytvořena,
• 204 Nema sadržaja – odpověď na váš požadavek neobsahuje žádná data,
• 400 Loš zahtjev – data odeslaná klientem nejsou platná (podrobný popis chyby je vrácen v poruka atribut),
• 401 Neovlašteno – neoprávněný přístup, chybějící nebo špatné client_id,
• 404 Nije pronađeno – požadovaná data nenalezena,
• 500 Interna pogreška poslužitelja – interní chyba serveru je způsobena např. nedostupným přístupem k jednomu ze systémových rozhraní (databáze, webové služby, SAP atd.).

API funkcije

Funkcija API pozivaju se odgovarajućim metodama HTTP:

• DOBITI vraća podatke o objektu, ne vrši nikakve promjene,
• POST šalje novi podatkovni objekt,
• STAVITI ažurira postojeći podatkovni objekt,
• IZBRISATI briše podatkovni objekt.

Validacija podataka

API zahtjevi se validiraju. Ako postoje greške koje treba ispraviti, u tijelu odgovora vraća se popis grešaka.

Neobavezni parametri

Ako je svojstvo opcionalno i ne želite ga koristiti, nemojte ga stavljati u API zahtjev. Postavljanje prazne vrijednosti vratit će poruku o pogrešci. Ključ {key} ne postoji ili je prazan.

Slike

Za ažuriranje slike proizvoda/varijante morate promijeniti URL slike.
Na primjer, dodavanjem parametra u oblik VREMENSKA ŽIGA ili ID proizvoda/varijante na URL slike.
Maksimalna rezolucija slike je 2000 piksela x 2000 piksela, minimalna veličina slike je 100 KB, a maksimalna veličina je 2 MBMaksimalni broj slika po proizvodu je 20. Maksimalno vrijeme odgovora za URL slike je 1 sekunda. URL slike ne smije sadržavati razmake ili dijakritičke znakove.

Energetska oznaka

Smjernice za nove energetske oznake

• Potrebno je dodati sliku energetske oznake na medij na 3.-4. mjestu, sliku informativnog lista i dodati elemente energy_label/information_list = true/false i switch=false
• ispunite parametar ENERGY_CLASS
• provjerite sadrže li svi tekstovi proizvoda (opisi/nazivi) točne i ažurne informacije

Zaštita od neželjenih promjena cijena proizvoda

U situaciji kada partner ažurira proizvode na različitim e-trgovinama s različitim valutama, postoje određeni rizici.
Moguće je da partner pošalje cijenu proizvoda u pogrešnoj valuti. Kako bi se djelomično uklonio ovaj rizik, postavljen je prag zaštite cijene proizvoda.
Dopuštena razlika u cijeni između stare i nove cijene proizvoda/varijante je 30 %.

Ako je promjena cijene proizvoda/varijante veća od navedenog ograničenja, vraća se u odgovoru force_token i proizvod/varijanta nisu ažurirani.

Proizvod sa značajnom razlikom u cijeni stoga se može ažurirati samo kada se koristi force_token dobiveno iz neuspjelog ažuriranja proizvoda. U sljedećem zahtjevu potrebno je poslati dobiveno force_token kao parametar URL-a.

Primjer:
https://mpapi.mallgroup.com/v1/products/{productId}?client_id={clientId}&force_token={forceToken}

Ažuriranjem cijene proizvoda uz pomoć force_token, partner potvrđuje da je nova cijena ispravna i da preuzima punu odgovornost za ovu novopostavljenu cijenu.
U tim slučajevima potreban je oprez i stoga se ne preporučuje korištenje force_token automatski. Sve promjene i korištenja tokena bilježi MALL.
U zemljama izvan Češke Republike, koristite kao razdjelnik iznosa tečku „.“.

Primjer:

{ "errorCodes": [ { "message": "Razlika između trenutne cijene ({value of current price}) i nove cijene ({value of new price}) za proizvod "{product id}" veća je od 30% ({real percentage difference}). Za potvrdu ove promjene upotrijebite priloženi force token.", "errorCode": "INCORRECT_PRODUCT_PRICE_DIFFERENCE", "errorAttributes": { "current": "currentPrice", "new": "newPrice", "id": "productId" } } ], "result": { "code": 400, "status": "ERROR", "message": "Razlika između trenutne cijene ({value of current price}) i nove cijene ({value of new price}) za proizvod "{product id}" veća je od 30% ({real percentage difference}). Za potvrdu ove promjene upotrijebite priloženi force token." }, "podaci": { "ključ": "proizvod.varijante", "podaci": { "forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679", "indeks varijante": 0 } } }

API krajnje točke

• Robne marke – Výpis dostupných značek.
• Kategorija – Seznam dostupných kategorií, produktových parametrů dostupných pro tyto kategorie a případně dostupné hodnoty těchto parametrů a strom MENU MALL/MIMOVRSTE.
  Potrebne informacije možete pronaći i na portalu MALL Partner u odjeljku Kategorija.
  Detaljniji opis kategorija, parametara sortiranja i njihovih vrijednosti možete pronaći u članku ovdje.
• Prijevozi – Seznam dopravců, kteří jsou založeni na straně MALL a jejich detail. Partner si z tohoto seznamu „vybírá“ dopravce, které bude využívat.
• Dostave – Dopravy založené partnerem a zasílané zpět do MALL. Partnerem zaslané dopravy budou následně dostupné v nákupním košíku.
• Oznake – List všech dostupných štítků/nálepek. Partner využívá štítky v rámci podpory prodeje na základě pokynu ze strany MALL/MIMOVSRTE.
• Narudžbe – Veškerá dostupná data o objednávkách. Obsahuje výpis všech objednávek, výpis základních dat o všech objednávkách, seznamy objednávek podle různých stavů, detail objednávky, aktualizaci objednávky, generování oznake za prijevoz u trgovačkom centru a další. V rámci bezpečnosti (zamezení odesílání nepřipravených objednávek partnerem) jsou z určitých výpisů záměrně odebrány objednávky ve stavu „blocked“ a je tedy třeba je volat zvlášť. Změny u objednávek je možné sledovat pomocí nástroje webhook.
• Proizvodi – Zakládání, editace a mazání partnerských produktů. Obsahuje výpis všech produktů, výpis základních dat o všech produktech, založení nových produktů, aktivaci „draft“ produktů, aktualizaci dostupnosti a cen produktů a další.
• Varijante – Obdobně jako produkty je možné zakládat, editovat a mazat varianty partnerských produktů.
• Verifikacija – Ověření konzistence dat. V možnostech je ověření doprav (deliveries) a medií.
• Fakture – Seznamy a detail faktur v případě, že partner využívá Samonaplata u trgovačkom centruMogućnost preuzimanja računa kao datoteke.
• Zasluge – Seznamy a detail zápočtů v případě, že partner využívá Samonaplata u trgovačkom centruMogućnost preuzimanja kredita kao datoteke.