API-kapcsolati utasítások

Az API-kapcsolat (MPAPI) az Ön áruházának és a MALL/MIMOVRSTE Partner környezetének összekapcsolására szolgál, azaz a termékekre és azok változataira, a szállítási beállításokra és nem utolsósorban a megrendelések feldolgozására vonatkozó információk cseréjére.

Az API az úgynevezett REST architektúrán alapul, amely lehetővé teszi az adatokhoz való hozzáférést és az azokon végzett műveleteket, mint például az adatdömping, az objektumok (termékek, szállítások stb.) létrehozása, frissítése vagy törlése.
Az API biztonságos HTTPS-kapcsolatot használ.

A működőképes kapcsolathoz egyedi kulcsot kell beszerezni a MALL Partnertől. client_id, amely a küldött kérelmek engedélyezésére szolgál.

Ezeket a kéréseket a következő címre küldik https://mpapi.mallgroup.com/ termelési környezetben, függetlenül attól, hogy melyik országban kínálja termékeit.
Az országot a következőkkel azonosítják client_id.

Minden adatot elküldünk és JSON formátumban és UTF-8 kódolásban érkeznek vissza. Az elküldött kérésre adott válasz a következőket adja vissza mindig HTTP-kódot, a megfelelő metódusokban adatokat és esetleg lapozást is.

{
   "result": {
         "code": 200/400/403/404/500,
         "status": OK/ERROR/LIMITED,
         "message": további üzenet
   },
   "paging": {
         "pages": az oldalak száma,
         "size": az oldalon lévő elemek száma,
         "page": aktuális oldal
   },
   "data": {
          strukturált adatok
   }
}

A HTTP-kódokról, a lapozás használatáról és különösen az előírt adatszerkezetről részletes információ a következő dokumentumban található online dokumentáció.

A gyorsabb megvalósítás érdekében a következők állnak rendelkezésre MPAPI ügyfél (jelenleg csak PHP-ben, az 5.5-ös és újabb verzió támogatott). Letöltési információk és a legújabb verzió a következő címen található meg packagist.org/packages/mallgroup/mpapi-client.

Changelog

Online dokumentáció naprakész információkat tartalmaz. Minden változás a Changelog szakaszban kerül rögzítésre, beleértve az érvényesség dátumát is.

API architektúra

Az MP API szoftverarchitektúrán alapul REST és biztosítva HTTPS protokoll.

API végpontok

1. Átlátható proxy

• Független API-teszteléshez használhat egy átlátható proxy-t (az online dokumentációból hívhatja a módokat Mock szerver vagy Proxy hibakeresés),
• kattintson a felső menüben az Ellenőr linkre, hogy figyelemmel kísérje a proxy banner kéréseket,
• ha nem használ transzparens proxyt, akkor a kéréseket közvetlenül az URI végpontokra küldheti a termelési környezetben.

2. Termelési környezet

• A gyártó API URL-je a következő címen érhető el https://mpapi.mallgroup.com/v1/, az URL minden nyelvre érvényes, de minden országra más és más érvényes. client_id.

Engedélyezés

Minden kérelemnek tartalmaznia kell engedélyezési kulcs (ügyfél azonosító). Ez a kulcs a partnerek számára elérhető a partnerportálon.

Adatformátum

Minden adat a következő formátumban van JSON és kódolva UTF-8. A tartalom típusa beállítható Content-Type: application/json vagy Content-Type: application/json; Charset=UTF-8.

Retrieved from

A kimenet a következő szerkezetű:

{
    "result": {
        "code": 200/400/403/404/500,
        "status": OK/ERROR/LIMITED,
        "message": további hibainformáció
    },
    "paging": {
        "pages": az oldalak száma,
        "size": az objektumok száma egy oldalon,
        "page": az aktuális oldal száma
    },
    "data": {
        adatszerkezet
    }
}

A DELETE kérések nem küldenek vissza semmilyen tartalmat (204-es kód).

Eredmény

Az eredmény a következő HTTP kód, állapot és hibaüzenet.

Oldalszámozás

Objektum lapozás akkor használatos, ha a kimenet több oldalra van osztva.
A lapozás az URL paraméterekkel történő meghívásával állítható be. oldal a page_size. Az alapértelmezett oldalméret (és egyben az ajánlott maximális érték) a következő 100.

Példa:
https://mpapi.mallgroup.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}

Adatok

Az adatszerkezet a végponttól függően változik, és minden egyes végpontra külön-külön a következő dokumentumban van leírva online dokumentáció.

HTTP állapotkódok

• 200 OK - minden rendben van, az adatok helyesen kerülnek vissza,
• 201 Létrehozva - a benyújtott adatok beérkeztek, és az entitást létrehozták,
• 204 Nincs tartalom - a kérésére adott válasz nem tartalmaz semmilyen adatot,
• 400 Rossz kérés - az ügyfél által küldött adatok nem érvényesek (a hiba részletes leírása a üzenet attribútum),
• 401 Nem engedélyezett - jogosulatlan hozzáférés, hiányzó vagy helytelen client_id,
• 404 Nem található - a kért adat nem található,
• 500 belső szerver hiba - A belső szerverhibát például az okozza, hogy a rendszer valamelyik interfészéhez (adatbázis, webes szolgáltatások, SAP stb.) nem lehet hozzáférni.

API funkciók

Funkciók API a megfelelő módszerek hívják meg HTTP:

• GET visszaadja az objektumra vonatkozó adatokat, nem végez semmilyen módosítást,
• POST új adatobjektumot küld,
• PUT egy meglévő adatobjektum frissítése,
• DELETE eltávolítja az adatobjektumot.

Adatérvényesítés

Az API-kérelmeket ellenőrzik. Ha vannak javítandó hibák, a válasz testében visszaküldjük a hibák listáját.

Választható paraméterek

Ha egy tulajdonság opcionális, és nem szeretné használni, ne adja meg az API-kérelemben. Ha üres értékkel állítja be, hibaüzenet érkezik vissza. A kulcs {key} nem létezik vagy üres.

Képek

A termék/variáns kép frissítéséhez a kép URL-címét kell megváltoztatni.
Például egy paraméter hozzáadásával a következő formában TIMESTAMP vagy Termék azonosító/változatok a kép URL címéhez.
A képek maximális felbontása 2000 px x 2000 px, a minimális képméret 100 KB, a maximális méret pedig 2 MB. A képek maximális száma termékenként 20. A kép URL címe nem tartalmazhat szóközöket és diakritikus jeleket.

Energiacímke

Útmutató az új energiacímkékről

• az energiacímke képét a 3.-4. pozícióban kell hozzáadni a médiához, az információs lap képét, és hozzá kell adni az energy_label/information_list = true/false és switch=false elemeket.
• töltse ki az ENERGY_CLASS paramétert
• ellenőrizze, hogy minden termékszöveg (leírás/elnevezés) tartalmazza-e a helyes, naprakész információkat

Védelem a termékár nem szándékos változásai ellen

Bizonyos kockázatokkal jár, ha egy partner különböző pénznemű webáruházakban frissíti a termékeket.
Előfordulhat, hogy a partner rossz pénznemben küldi a termék árát. E kockázat részleges kiküszöbölése érdekében a termék árának védelmére küszöbértéket állítunk be.
A termék/variáns régi és új ára közötti megengedett árkülönbség a következő 30 %.

Ha a termék/variáns árváltozása magasabb, mint a határérték, a válaszban visszaküldjük. force_token és a termék/variáns nem frissül.

A jelentős árkülönbséggel rendelkező termék tehát csak a következő eszközökkel frissíthető force_token egy sikertelen termékfrissítésből. A következő kérésben el kell küldenie a lekérdezett force_token URL paraméterként.

Példa:
https://mpapi.mallgroup.com/v1/products/{productId}?client_id={clientId}&force_token={forceToken}

A termék árának frissítésével a force_token, a partner megerősíti, hogy az új ár helyes, és hogy teljes felelősséget vállal az új árért.
Ezekben az esetekben helyben óvatosnak kell lenni, ezért nem tanácsos használni a force_token automatikusan. A MALL minden módosítást és tokenhasználatot rögzít.
A Cseh Köztársaságon kívüli országokban mennyiségleválasztóként kell használni. pont ".".

Példa:

{
  "errorCodes": [
    {
      "message": "A "{termék azonosító}" termék jelenlegi ára ({a jelenlegi ár értéke}) és új ára ({az új ár értéke}) közötti különbség nagyobb, mint 30% ({valós százalékos különbség}). A változás megerősítéséhez használja a csatolt force tokent.",
      "errorCode": "INCORRECT_PRODUCT_PRICE_DIFFERENCE",
      "errorAttributes": {
        "current": "currentPrice",
        "new": "newPrice",
        "id": "productId"
      }
    }
  ],
  "result": {
    "code": 400,
    "status": "ERROR",
    "message": "A "{termék azonosító}" termék jelenlegi ára ({a jelenlegi ár értéke}) és új ára ({az új ár értéke}) közötti különbség nagyobb, mint 30% ({valós százalékos különbség}). A változás megerősítéséhez használja a csatolt force tokent."
  },
  "data": {
    "key": "product.variants",
    "data": {
      "forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679",
      "variantIndex": 0
    }
  }
}

API végpontok

• Márkák (márkák) - Az elérhető márkák listája.
• Kategória - Az elérhető kategóriák, az ezekhez a kategóriákhoz elérhető termékparaméterek és adott esetben e paraméterek elérhető értékeinek listája, valamint a MENÜ MALL/MIMOVRSTE fa.
  A szükséges adatok a MALL Partner Portálon is megtalálhatók a következő menüpontban Kategória.
  A kategóriák, a rendezési paraméterek és értékeik részletesebb leírását lásd a következő cikkben itt.
• Közlekedés (szállítás) - A MALL oldalon működő fuvarozók listája és azok részletei. A partner ebből a listából "választja ki" a használni kívánt fuvarozókat.
• Szállítás (szállítások) - A partner által létrehozott és a MALL-nak visszaküldött küldemények. A partner által küldött küldemények ezután elérhetőek lesznek a kosárban.
• Címkék - Az összes rendelkezésre álló címke/matrica lapja. A partner a MALL/MIMOVSRTE utasításai alapján a címkéket az értékesítésösztönzés keretében használja fel.
• Megrendelések - Minden rendelkezésre álló rendelési adat. Tartalmazza az összes rendelés listáját, az összes rendelés alapadatainak listáját, a különböző státuszok szerinti rendelési listákat, a rendelés részletezését, a rendelés frissítését, a rendelés generálását. címkék a MALL szállításhoz és mások. Biztonsági intézkedésként (annak megakadályozása érdekében, hogy a partner előkészítetlen megrendeléseket küldjön) a "blokkolt" státuszban lévő megrendelések szándékosan kerülnek ki bizonyos listákból, ezért külön kell őket hívni. A megrendelések változásai nyomon követhetők a webhook.
• Termékek - Partnertermékek létrehozása, szerkesztése és törlése. Tartalmazza az összes termék felsorolását, az összes termék alapadatainak felsorolását, új termékek létrehozását, a "tervezet" termékek aktiválását, a termékek elérhetőségének és árazásának frissítését és még sok mást.
• Változatok - A termékekhez hasonlóan a partnertermékek változatait is létrehozhatja, szerkesztheti és törölheti.
• Ellenőrzés - Az adatok konzisztenciájának ellenőrzése. A lehetőségek közé tartozik a szállítás (szállítás) és a hordozók ellenőrzése.
• Számlák - A számlák listái és részletei, ha a partner a következő szolgáltatásokat használja MALL önszámlázás. A számla letölthető fájlként.
• Hitelek - A hitelek listája és részletei, ha a partner használja MALL önszámlázás. A hitel letölthető fájlként.