Navodila za povezavo API

Povezava API (MPAPI) se uporablja za povezavo vaše trgovine in partnerskega okolja MALL / MIMOVRSTE, torej za izmenjavo informacij o izdelkih in njihovih različicah, o nastavitvah prevoza in nenazadnje za obdelavo naročil.

API temelji na tako imenovani REST arhitekturi, ki omogoča dostop do podatkov in izvajanje operacij na njih, kot so naštevanje podatkov, ustvarjanje, posodabljanje ali brisanje ustvarjenih predmetov (izdelki, transport itd.).
API uporablja varno povezavo HTTPS.

Za funkcionalno povezavo je treba od partnerja MALL - client_id pridobiti unikatni ključ, ki se uporablja za avtorizacijo poslanih zahtev.

Te zahteve so poslane na https://mpapi.mallgroup.com/ v proizvodnem okolju, ne glede na državo, v kateri boste ponujali svoje blago.
Država je označena z client_id.

Vsi podatki so poslani in vrnjeni v obliki JSON in v kodiranju UTF-8. Odgovor na poslano zahtevo vedno vrne kodo HTTP, v ustreznih metodah tudi podatke in po možnosti tudi ostranjevanje.

{"rezultat": {"koda": 200/400/403/404/500, "status": OK / ERROR / LIMITED, "message": dodatno sporočilo}, "paging": {"pages": število strani, "size": število elementov na stran, "page": current page}, "data": {structured data}}

Podrobne informacije o kodah HTTP, uporabi strani in zlasti predpisani strukturi podatkov so na voljo v spletni dokumentaciji .

Za hitrejšo implementacijo je na voljo odjemalec MPAPI (trenutno je podprt samo v PHP, različica 5.5 in novejša). Podatke o prenosu in najnovejšo različico najdete na spletnem mestu Packagist.org/packages/mallgroup/mpapi-client .

Dnevnik sprememb

Spletna dokumentacija vsebuje aktualne informacije. Vse spremembe so zabeležene v razdelku Dnevnik sprememb, vključno z datumom poteka veljavnosti.

Arhitektura API

MP API temelji na programski arhitekturi REST in je zaščiten s protokolom HTTPS .

Končne točke API

1. Prozoren proxy

• Za neodvisno preskušanje API-jev lahko uporabite prosojni strežnik proxy (iz spletne dokumentacije lahko pokličete načine Mock Server ali Debugging Proxy ),
• Prošnjam za proxy lahko sledite tako, da kliknete povezavo Inspector v zgornjem meniju.
• če ne uporabljate prosojnega strežnika proxy, lahko zahteve pošljete neposredno končnim točkam URI v produkcijskem okolju.

2. Proizvodno okolje

• URL produkcijskega API-ja najdete na https://mpapi.mallgroup.com/v1/ , URL je veljaven za vsako jezikovno različico, vendar za vsako državo velja drugačen client_id .

Pooblastilo

Vsaka zahteva mora vsebovati avtorizacijski ključ (id stranke). Ta ključ je na voljo partnerjem na partnerskem portalu.

Podatkovna oblika

Vsi podatki so v obliki JSON in kodirani kot UTF-8 . Vsebino lahko nastavite na Content-Type: application / json ali Content-Type: application / json; Charset = UTF-8 .

Izhod

Rezultat je v naslednji strukturi:

{"result": {"code": 200/400/403/404/500, "status": OK / ERROR / LIMITED, "message": dodatne informacije o napaki}, "paging": {"pages": število strani, "velikost": število predmetov na strani, "stran": število trenutne strani}, "podatki": {struktura podatkov}}

Zahteve DELETE ne vrnejo nobene vsebine (koda 204).

Rezultat

Rezultat vrne kodo HTTP , stanje in sporočilo o napaki.

Paginacija

Ostranjevanje predmetov se uporablja, kadar je izhod razdeljen na več strani.
Ostranjevanje lahko nastavite tako, da pokličete URL s parametri page in size_size . Privzeta velikost strani (pa tudi priporočena največja) je 100 .

Na 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 v spletni dokumentaciji opisana za vsako končno točko posebej.

Kode stanja HTTP

• 200 OK - vse je v redu, podatki so vrnjeni pravilno,
• 201 Ustvarjeno - poslani podatki so bili prejeti in entiteta je bila ustvarjena,
• 204 Brez vsebine - odgovor na vašo zahtevo ne vsebuje nobenih podatkov,
• 400 Slaba zahteva - podatki, ki jih pošlje odjemalec, niso veljavni (podroben opis napake je vrnjen v atributu sporočila ),
• 401 Nepooblaščeno - nepooblaščen dostop, manjkajoč ali slab client_id ,
• 404 ni mogoče najti - zahtevanih podatkov ni mogoče najti,
• 500 Notranja napaka strežnika - napako notranjega strežnika povzroča, na primer, nerazpoložljiv dostop do enega od sistemskih vmesnikov (zbirke podatkov, spletne storitve, SAP itd.).

API funkcije

Funkcije API se pokličejo z ustreznimi metodami HTTP :

• GET vrne podatke o objektu, ne naredi nobenih sprememb,
• POST pošlje nov podatkovni objekt,
• PUT posodobi obstoječi podatkovni objekt,
• DELETE izbriše podatkovni objekt.

Preverjanje podatkov

Zahteve za API so preverjene. Če obstajajo napake, ki jih je treba popraviti, se v telesu odziva vrne seznam napak.

Neobvezni parametri

Če lastnost ni obvezna in je ne želite uporabljati, je ne vključite v zahtevo za API. Če jo nastavite s prazno vrednostjo, se vrne sporočilo o napaki Key {key} ali je prazno .

Slike

Če želite posodobiti sliko izdelka / različice, morate spremeniti URL slike.
Na primer z dodajanjem parametra v obrazec TIMESTAMP ali ID izdelka / variante na URL slike.
Največja ločljivost slik je 2000 px x 2000 px, je najmanjša velikost slike 100 KB, največja pa 2 MB. Največje število slik za izdelek je 20. Najdaljši odzivni čas URL-ja slike je 1 s. URL slike ne sme vsebovati presledkov ali naglasov.

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

V situaciji, ko partner posodablja izdelke na različnih e-trgovinah z različnimi valutami, obstajajo določena tveganja.
Partner lahko pošlje ceno izdelka v napačni valuti. Da bi to tveganje delno odpravili, je določena meja za zaščito cen izdelkov.
Dovoljena razlika v ceni med staro in novo ceno izdelka / variante je 30 % .

Če je sprememba cene izdelka / variante višja od nastavljene meje, se v odgovor vrne force_token in izdelek / varianta ni posodobljen.

Izdelek s pomembno razliko v ceni je zato mogoče posodobiti samo ob uporabi force_token pridobljeno iz neuspešne posodobitve izdelka. V naslednji zahtevi je potrebno poslati pridobljeno force_token kot parameter URL-ja.

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

S posodabljanjem cene izdelka s pomočjo force_token, partner potrjuje, da je nova cena pravilna in da prevzema polno odgovornost za to novo določeno ceno.
V teh primerih je lokalna previdnost in se je ne sme uporabljati force_token samodejno. Vse spremembe in uporabo žetonov zabeleži MALL.
Uporaba v državah zunaj Češke republike kot ločilo količine pika ".".

Primer:

{"errorCodes": [{"message": "Razlika med trenutno ceno ({vrednost trenutne cene}) in novo ceno ({vrednost nove cene}) za izdelek" {product id} "je večja od 30% ({real za potrditev te spremembe uporabite priloženi žeton sile. "," errorCode ":" INCORRECT_PRODUCT_PRICE_DIFFERENCE "," errorAttributes ": {" current ":" currentPrice "," new ":" newPrice "," id ": "productId"}}], "result": {"code": 400, "status": "ERROR", "message": "Razlika med trenutno ceno ({vrednost trenutne cene}) in novo ceno ({vrednost nova cena}) za izdelek "{product id}" je večji od 30% ({realna odstotna razlika}). Če želite potrditi to spremembo, uporabite priloženi žeton sile. " }, "data": {"key": "product.variants", "data": {"forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679", "variantIndex": 0}}}

Končne točke API

• Blagovne znamke - seznam razpoložljivih blagovnih znamk.
• Kategorije - Seznam razpoložljivih kategorij, parametri izdelkov, ki so na voljo za te kategorije, in morebitne razpoložljive vrednosti teh parametrov ter drevo MENU MALL.
  Potrebne podatke boste našli tudi na partnerskem portalu MALL v razdelku Kategorije.
  Podrobnejši opis kategorij, parametrov razvrščanja in njihovih vrednosti najdete v članku tukaj..
• Prevozi - seznam prevoznikov, ki temeljijo na strani MALL in njihove podrobnosti. S tega seznama partner "izbere" prevoznika, ki ga bo uporabil.
• Prevozi - prevozi, ki jih je vzpostavil partner in jih poslal nazaj v MALL. Prevoz, ki ga pošlje partner, bo nato na voljo v nakupovalni košarici.
• Oznake - seznam vseh razpoložljivih oznak. Partner uporablja etikete kot del prodajne podpore na podlagi navodil podjetja 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 več. Kot del varnosti (preprečevanje pošiljanja nepripravljenih naročil s strani partnerja) se naročila v "blokiranem" stanju namerno odstranijo iz nekaterih izjav in jih je zato treba poklicati ločeno. Spremembe naročil lahko spremljate z orodjem spletni kavelj.
• Izdelki - Ustvarjanje, urejanje in brisanje partnerskih izdelkov. Vsebuje seznam vseh izdelkov, seznam osnovnih podatkov o vseh izdelkih, ustvarjanje novih izdelkov, aktiviranje "osnutkov" izdelkov, posodobitev razpoložljivosti izdelkov in cen ter drugo.
• Različice - Podobno kot pri izdelkih je mogoče ustvarjati, urejati in brisati različice partnerskih izdelkov.
• Preverjanje - preverite skladnost podatkov. Možnosti vključujejo preverjanje pošiljk in medijev.
• Računi - Seznami in podrobnosti računov, če jih partner uporablja MALL Self-Billing. Možnost prenosa računa kot datoteke.
• Zasluge - Seznami in podrobnosti dobropisov, če jih partner uporablja MALL Self-Billing. Možnost prenosa dobropisa kot datoteke.