Navodila za povezavo API

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.

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.