Ikona spletnega mesta MALL Partner - Pomoč na trgu

Navodila za povezavo API

ngeorgievova

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

2. Proizvodno okolje

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

Funkcije API

Funkcije API se kličejo z ustreznimi metodami HTTP:

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

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

Kako koristna je bila ta objava?

Kliknite na zvezdico, da ocenite objavo!

Povprečna ocena: 3 / 5. Število glasov: 4

Nihče še ni glasoval. Bodite prvi in ocenite to objavo.

Izhod iz mobilne različice