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, koji se koristi za autorizaciju poslanih zahtjeva.

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 } }

Detaljne informacije o HTTP kodovima, korištenju paginacije i posebno propisanoj strukturi podataka dostupne su u 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 – sve je u redu, podaci se vraćaju ispravno,
• 201 Kreirano – poslani podaci su primljeni i entitet je kreiran,
• 204 Nema sadržaja – odgovor na vaš zahtjev ne sadrži nikakve podatke,
• 400 Loš zahtjev – podaci koje je poslao klijent nisu valjani (detaljan opis greške vraća se u poruka atribut),
• 401 Neovlašteno – neovlašteni pristup, nedostajući ili netočni client_id,
• 404 Nije pronađeno – traženi podaci nisu pronađeni,
• 500 Interna pogreška poslužitelja – interna pogreška poslužitelja uzrokovana je, na primjer, nedostupnim pristupom jednom od sistemskih sučelja (baza podataka, web servisi, SAP itd.).

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 točka ".".

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 – Popis dostupnih marki.
• Kategorija – Popis dostupnih kategorija, parametara proizvoda dostupnih za te kategorije i, ako je primjenjivo, dostupnih vrijednosti za te parametre te stablo IZBORA TRGOVAČKI CENTAR/NE-KATEGORIJE.
  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 – Popis prijevoznika koji se temelje na MALL strani i njihovi detalji. Partner „odabire“ prijevoznika kojeg će koristiti s ovog popisa.
• Dostave – Pošiljke koje je kreirao partner i poslao natrag u MALL. Pošiljke koje je poslao partner tada će biti dostupne u košarici.
• Oznake – Popis svih dostupnih etiketa/naljepnica. Partner koristi etikete kao dio prodajne podrške na temelju uputa iz MALL-a/MIMOVSRTE-a.
• Narudžbe – Svi dostupni podaci o narudžbi. Sadrži popis svih narudžbi, popis osnovnih podataka o svim narudžbama, popise narudžbi prema različitim statusima, detalje narudžbe, ažuriranja narudžbi, generiranje oznake za prijevoz u trgovačkom centru i drugi. Iz sigurnosnih razloga (kako bi se spriječilo da partner šalje nepripremljene naloge), nalozi u statusu "blokirano" namjerno se uklanjaju iz određenih izvoda i stoga ih je potrebno zasebno pozivati. Promjene naloga mogu se pratiti pomoću alata webhook.
• Proizvodi – Izrada, uređivanje i brisanje partnerskih proizvoda. Uključuje popis svih proizvoda, popis osnovnih podataka o svim proizvodima, izradu novih proizvoda, aktiviranje nacrta proizvoda, ažuriranje dostupnosti i cijena proizvoda i još mnogo toga.
• Varijante – Slično kao i kod proizvoda, moguće je kreirati, uređivati i brisati varijante partnerskih proizvoda.
• Verifikacija – Provjera konzistentnosti podataka. Mogućnosti uključuju provjeru isporuke i medija.
• Fakture – Popisi i detalji računa ako partner koristi Samonaplata u trgovačkom centruMogućnost preuzimanja računa kao datoteke.
• Zasluge – Popisi i detalji o kreditima ako ih partner koristi Samonaplata u trgovačkom centruMogućnost preuzimanja kredita kao datoteke.