Povezava API (MPAPI) se uporablja za povezovanje vaše trgovine z okoljem MALL/MIMOVRSTE Partner, tj. za izmenjavo informacij o izdelkih in njihovih različicah, nastavitvah prevoza in nenazadnje za obdelavo naročil.
API temelji na tako imenovani arhitekturi REST, ki omogoča dostop do podatkov in izvajanje operacij z njimi, kot so izpis podatkov, ustvarjanje, posodabljanje ali brisanje objektov (izdelkov, prevozov itd.).
API uporablja varno povezavo HTTPS.
Za funkcionalno povezavo je treba od partnerja MALL pridobiti edinstven ključ. client_id, ki se uporablja za avtorizacijo poslanih zahtevkov.
Ti zahtevki so poslani https://mpapi.mallgroup.com/ v proizvodnem okolju, ne glede na državo, v kateri ponujate svoje blago.
Država je označena z client_id.
Vsi podatki so poslani in vrnejo v formatu JSON in kodiranju UTF-8. Odgovor na poslano zahtevo vrne vedno kodo HTTP, v ustreznih metodah pa tudi podatke in po možnosti tudi strani.
{
"rezultat": {
"koda": 200/400/403/404/500,
"status": OK/ERROR/LIMITED,
"message": dodatno sporočilo
},
"paging": {
"pages": število strani,
"velikost": število elementov na strani,
"page": trenutna stran
},
"data": {
strukturirani podatki
}
}
Podrobne informacije o kodah HTTP, uporabi paginacije in zlasti predpisani strukturi podatkov so na voljo v spletna dokumentacija.
Za hitrejše izvajanje je na voljo naslednje Odjemalec MPAPI (trenutno samo v PHP, podprta je različica 5.5 in novejša). Informacije o prenosu in najnovejšo različico najdete na packagist.org/packages/mallgroup/mpapi-client.
Seznam sprememb
Spletna dokumentacija vsebuje najnovejše informacije. Vse spremembe so zabeležene v razdelku Changelog, vključno z datumom veljavnosti.
Arhitektura API
API MP temelji na arhitekturi programske opreme REST in zavarovana HTTPS protokol.
Končne točke API
1. Transparentni proxy
- Za neodvisno testiranje API lahko uporabite pregleden posrednik (načine lahko prikličete iz spletne dokumentacije Posnemovalni strežnik ali Razhroščevanje proxy strežnika),
- kliknite povezavo Inspector v zgornjem meniju in spremljajte zahteve za proxy banner,
- če ne uporabljate prozornega posrednika, lahko pošljete zahteve neposredno končnim točkam URI v produkcijskem okolju.
2. Proizvodno okolje
- URL produkcijskega API-ja je na voljo na naslovu https://mpapi.mallgroup.com/v1/, URL velja za vse jezike, vendar za vsako državo velja drugačen. client_id.
Avtorizacija
Vsaka zahteva mora vsebovati ključ za avtorizacijo (identiteta stranke). Ta ključ je partnerjem na voljo na partnerskem portalu.
Format podatkov
Vsi podatki so v obliki JSON in kodiran kot UTF-8. Vrsto vsebine lahko nastavite kot Content-Type: application/json ali Content-Type: application/json; Charset=UTF-8.
Identifikacija predmetov
Vsi predmeti v vmesniku (npr. izdelki/variante) morajo imeti edinstven identifikator, ki ga upravlja partner:
- MALL partnerjem ne dodeli nobene serije številk,
- Identifikatorji lahko vsebujejo kombinacije do 50 znakov, dovoljeni znaki so: _ - 0-9 a-z A-Z (podčrtaje, pomišljaji, številke od nič do devet, velike in male črke brez narekovajev).
- Identifikator mora biti edinstven na ravni partnerja.
Izjeme so na primer naročila, prevozi ali računi. V primeru naročil bo MALL/MIMOVRSTE ustvaril order_id, ki je nato na voljo na primer v seznam odprtih naročil. Ta ID je številčen in ga je treba uporabiti pri obdelavi naročila.
Obvestilo:
MALL order_id presega največjo dovoljeno velikost celega števila za 32-bitno različico PHP. Da bi se izognili nekonsistentnim podatkom za naročila, uporabite 64-bitno različico.
Pridobljeno iz
Rezultat ima naslednjo strukturo:
{
"rezultat": {
"koda": 200/400/403/404/500,
"status": OK/ERROR/LIMITED,
"message": dodatne informacije o napaki
},
"paging": {
"pages": število strani,
"velikost": število predmetov na strani,
"page": številka trenutne strani
},
"data": {
podatkovna struktura
}
}
Zahteve DELETE ne vrnejo nobene vsebine (koda 204).
Rezultat
Rezultat vrne HTTP kodo, status in morebitno sporočilo o napaki.
Paginacija
Objekt paging se uporablja, kadar je izpis razdeljen na več strani.
Strani lahko nastavite tako, da pokličete URL s parametri stran in page_size. Privzeta velikost strani (in tudi priporočena največja vrednost) je 100.
Primer:
https://mpapi.mallgroup.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}
Podatki
Struktura podatkov se razlikuje glede na končno točko in je opisana za vsako končno točko posebej v spletna dokumentacija.
Kode stanja HTTP
- 200 OK - vse je v redu, podatki se vrnejo pravilno,
- 201 Ustvarjeno - prejeti so bili predloženi podatki in entiteta je bila ustvarjena,
- 204 Brez vsebine - odgovor na vašo zahtevo ne vsebuje nobenih podatkov,
- 400 Slaba zahteva - podatki, ki jih je poslal odjemalec, niso veljavni (podroben opis napake je vrnjen v sporočilo atribut),
- 401 Nepooblaščeno - nepooblaščen dostop, manjkajoči ali nepravilni client_id,
- 404 Ni mogoče najti - zahtevani podatki niso bili najdeni,
- 500 notranja napaka strežnika - Notranja napaka strežnika je na primer posledica nedostopnega dostopa do enega od sistemskih vmesnikov (zbirka podatkov, spletne storitve, SAP itd.).
Funkcije API
Funkcije API se kličejo z ustreznimi metodami HTTP:
- GET vrne podatke o objektu, ne izvede nobenih sprememb,
- POST pošlje nov podatkovni objekt,
- PUT posodobi obstoječi podatkovni objekt,
- DELETE odstrani podatkovni objekt.
Potrjevanje podatkov
Zahteve API so preverjene. Če se pojavijo napake, ki jih je treba odpraviti, se v telesu odgovora vrne seznam napak.
Neobvezni parametri
Če je lastnost neobvezna in je ne želite uporabiti, je ne vključite v zahtevo API. Če jo nastavite s prazno vrednostjo, bo vrnjeno sporočilo o napaki Ključ {key} ne obstaja ali je prazen.
Slike
Če želite posodobiti sliko izdelka/variante, morate spremeniti URL slike.
Na primer z dodajanjem parametra v obliki TIMESTAMP ali ID izdelka/variante v naslov URL slike.
Največja ločljivost slik je 2000 px x 2000 px, najmanjša velikost slike je 100 KB, največja pa 2 MB. Največje število slik na izdelek je 20. URL slike ne sme vsebovati presledkov in diakritičnih znakov.
Energijska nalepka
Smernice za nove energijske oznake
- v medij je treba dodati sliko energijske nalepke na 3.-4. mesto, sliko informativnega lista in elemente energy_label/information_list = true/false in switch=false
- izpolnite parameter ENERGY_CLASS
- preverite, ali vsa besedila izdelka (opisi / ime) vsebujejo pravilne informacije
Zaščita pred nenamernimi spremembami cene izdelka
Kadar partner posodablja izdelke v različnih e-trgovinah z različnimi valutami, obstajajo določena tveganja.
Lahko se zgodi, da partner pošlje ceno izdelka v napačni valuti. Za delno odpravo tega tveganja je določen prag za zaščito cene izdelka.
Dovoljena razlika v ceni med staro in novo ceno izdelka/variante je 30 %.
Če je sprememba cene izdelka/različice višja od omejitve, se vrne v odgovoru force_token in izdelek/različica se ne posodobita.
Izdelek z znatno razliko v ceni je zato mogoče nadgraditi le z uporabo force_token zaradi neuspešne posodobitve izdelka. V naslednjem zahtevku morate poslati pridobljeno force_token kot parameter URL.
Primer:
https://mpapi.mallgroup.com/v1/products/{productId}?client_id={clientId}&force_token={forceToken}
S posodabljanjem cene izdelka s pomočjo force_token, partner potrdi, da je nova cena pravilna in da prevzema polno odgovornost za novo ceno.
V teh primerih je potrebna previdnost na lokalni ravni, zato ni priporočljivo uporabljati force_token samodejno. MALL beleži vse spremembe in uporabo žetonov.
V državah zunaj Češke republike uporabite kot ločevalnik količin obdobje ".".
Primer:
{
"errorCodes": [
{
"message": "Razlika med trenutno ceno ({vrednost trenutne cene}) in novo ceno ({vrednost nove cene}) za izdelek "{izdelek id}" je večja od 30% ({resnični odstotek razlike}). Za potrditev te spremembe uporabite priloženi žeton sile.",
"errorCode": "INCORRECT_PRODUCT_PRICE_DIFFERENCE",
"errorAttributes": {
"current": "currentPrice",
"new": "newPrice",
"id": "productId"
}
}
],
"result": {
"koda": 400,
"status": "ERROR",
"message": "Razlika med trenutno ceno ({vrednost trenutne cene}) in novo ceno ({vrednost nove cene}) za izdelek "{izdelek id}" je večja od 30% ({resnični odstotek razlike}). Za potrditev te spremembe uporabite priloženi žeton sile."
},
"data": {
"key": "product.variants",
"data": {
"forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679",
"variantIndex": 0
}
}
}
Končne točke API
- Blagovne znamke (blagovne znamke) - Seznam razpoložljivih blagovnih znamk.
- Kategorije - Seznam razpoložljivih kategorij, parametrov izdelkov, ki so na voljo za te kategorije, in po potrebi razpoložljivih vrednosti teh parametrov ter drevo MENU MALL/MIMOVRSTE.
Potrebni podatki so na voljo tudi na portalu MALL Partner Portal v razdelku Kategorije.
Podrobnejši opis kategorij, parametrov razvrščanja in njihovih vrednosti najdete v članku tukaj. - Prevoz (transport) - Seznam prevoznikov s sedežem na strani MALL in njihove podrobnosti. Partner s tega seznama "izbere" prevoznike, ki jih bo uporabil.
- Prevoz (dobave) - Pošiljke, ki jih je ustvaril partner in jih poslal nazaj v MALL. Pošiljke, ki jih je poslal partner, bodo nato na voljo v nakupovalni košarici.
- Etikete - List z vsemi razpoložljivimi nalepkami. Partner uporablja nalepke v okviru pospeševanja prodaje na podlagi navodil MALL/MIMOVSRTE.
- Orders - Vsi razpoložljivi podatki o naročilu. Vključuje seznam vseh naročil, seznam osnovnih podatkov o vseh naročilih, sezname naročil po različnih statusih, podrobnosti o naročilu, posodobitev naročila, generiranje naročila nalepke za prevoz MALL in druge. Kot varnostni ukrep (da partner ne bi poslal nepripravljenih naročil) so naročila v statusu "blokirano" namerno odstranjena iz določenih seznamov, zato jih je treba klicati posebej. Spremembe naročil lahko spremljate z uporabo webhook.
- Izdelki - ustvarjanje, urejanje in brisanje partnerskih izdelkov. Vključuje seznam vseh izdelkov, osnovne podatke o vseh izdelkih, ustvarjanje novih izdelkov, aktiviranje "osnutkov" izdelkov, posodabljanje razpoložljivosti in cen izdelkov ter drugo.
- Variante - Podobno kot pri izdelkih lahko ustvarjate, urejate in brišete različice partnerskih izdelkov.
- Preverjanje - Preverjanje skladnosti podatkov. Možnosti vključujejo preverjanje prenosov (dostav) in nosilcev.
- Računi - Seznami in podrobnosti računov, če partner uporablja MALL Self-Billing. Račun lahko prenesete kot datoteko.
- Krediti - Seznami in podrobnosti o dobropisih, če partner uporablja MALL Self-Billing. Dobropis lahko prenesete kot datoteko.