Návod pro napojení API

Napojení API (MPAPI) slouží k provázání vašeho obchodu a prostředí MALL/MIMOVRSTE Partner, tedy k výměně informací o produktech a jejich variantách, o nastavení doprav a v neposlední řadě ke zprocesování objednávek.

API je postaveno na tzv. REST architektuře, která umožňuje přistupovat k datům a provádět nad nimi operace jako výpis dat, vytváření, aktualizace anebo mazání založených objektů (produktů, doprav apod.).
API využívá zabezpečené spojení protokolu HTTPS.

Pro funkční napojení je nutné získat ze strany MALL Partner unikátní klíč – client_id, který slouží k autorizaci zasílaných požadavků.

Tyto požadavky jsou posílány na https://mpapi.mallgroup.com/ v produkčním prostředí, a to bez ohledu na zemi, v níž budete své zboží nabízet.
Země je identifikována podle client_id.

Všechna data jsou posílána a vracena ve formátu JSON a v UTF-8 kódování. Odpověď na zaslaný požadavek vrací vždy HTTP kód, v odpovídajících metodách také data a případně i stránkování.

{
   "result": {
         "code": 200/400/403/404/500,
         "status": OK/ERROR/LIMITED,
         "message": doplňující zpráva
   },
   "paging": {
         "pages": počet stránek,
         "size": počet položek na stránce,
         "page": aktuální strana
   },
   "data": {
          strukturovaná data
   }
}

Podrobné informace k HTTP kódům, využití stránkování a zejména předepsané struktuře dat jsou k dispozici v online dokumentaci.

Pro rychlejší implementaci je k dispozici MPAPI client (v současnosti pouze v jazyce PHP, podporována je verze 5.5 a vyšší). Informace ke stažení a nejnovější verzi najdete na packagist.org/packages/mallgroup/mpapi-client.

Changelog

Online dokumentace obsahuje aktuální informace. Případné změny jsou zaznamenávány v sekci Changelog včetně data platnosti.

API architektura

MP API je založeno na softwarové architektuře REST a zabezpečeno HTTPS protokolem.

API endpointy

1. Transparent proxy

• Pro nezávislé testování API lze použít transparent proxy (z online dokumentace můžete volat režimy Mock Server nebo Debugging Proxy),
• kliknutím na odkaz Inspector v horní nabídce můžete sledovat své požadavky na transparent proxy,
• pokud nepoužijete transparent proxy, můžete požadavky poslat přímo do URI endpointy na produkčním prostředí.

2. Produkční prostředí

• URL produkčního API najdete na adrese https://mpapi.mallgroup.com/v1/, URL je platná pro každou jazykovou mutaci, avšak pro každou zemi platí odlišné client_id.

Autorizace

Každý požadavek musí obsahovat autorizační klíč (client id). Partnerům je tento klíč dostupný v partnerském portálu.

Formát dat

Všechna data jsou ve formátu JSON a kódována jako UTF-8. Content type lze nastavit jako Content-Type: application/json nebo Content-Type: application/json; Charset=UTF-8.

Výstup

Výstup je v následující struktuře:

{
    "result": {
        "code": 200/400/403/404/500,
        "status": OK/ERROR/LIMITED,
        "message": additional error information
    },
    "paging": {
        "pages": number of pages,
        "size": number of objects on a page,
        "page": number of current page
    },
    "data": {
        data structure
    }
}

DELETE požadavky nevracejí žádný obsah (kód 204).

Výsledek

Výsledek vrací HTTP kód, status a případnou chybovou zprávu.

Stránkování

Object paging je použit v případě, kdy je výstup rozdělen na více stránek.
Stránkování lze nastavit voláním URL s parametry page a page_size. Výchozí velikost stránky (a také doporučená maximální hodnota) je 100.

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

Data

Struktura dat se liší v závislosti na endpointu a je popsána pro každý endpoint zvlášť v online dokumentaci.

Stavové kódy HTTP

• 200 OK – vše je v pořádku, data jsou vrácena správně,
• 201 Created – odeslaná data byla přijata a entita byla vytvořena,
• 204 No content – odpověď na váš požadavek neobsahuje žádná data,
• 400 Bad Request – data odeslaná klientem nejsou platná (podrobný popis chyby je vrácen v message atributu),
• 401 Unauthorized – neoprávněný přístup, chybějící nebo špatné client_id,
• 404 Not Found – požadovaná data nenalezena,
• 500 Internal Server Error – interní chyba serveru je způsobena např. nedostupným přístupem k jednomu ze systémových rozhraní (databáze, webové služby, SAP atd.).

Funkce API

Funkce API jsou volány vhodnými metodami HTTP:

• GET vrací data o objektu, neprovádí žádné změny,
• POST odešle nový datový objekt,
• PUT aktualizuje existující datový objekt,
• DELETE odstraní datový objekt.

Validace dat

API požadavky jsou ověřeny. Pokud existují nějaké chyby, které je třeba opravit, je v těle odpovědi vrácen seznam chyb.

Volitelné parametry

Pokud je vlastnost volitelná a nechcete ji používat, nedávejte ji do požadavku na rozhraní API. Pokud ji nastavíte s prázdnou hodnotou, vrátí se chybová zpráva Key {key} does not exist or is empty.

Obrázky

Chcete-li aktualizovat obrázek produktu/varianty, je nutné URL adresu obrázku změnit.
Například přidáním parametru v podobě TIMESTAMP nebo ID produktu/varianty do URL adresy obrázku.
Maximální rozlišení obrázků je 2000 px x 2000 px, minimální velikost obrázku je 100 KB a maximální velikost je 2 MB. Maximální počet obrázků u produktu je 20. Maximální doba odezvy URL adresy obrázku je 1 s. URL obrázku nesmí obsahovat mezery a diakritiku.

Energetický štítek

Pokyny k novým energetickým štítkům

• je nutné přidat do médií obrázek Energetického štítku na 3.-4. místo, obrázek Informačního listu a doplnit elementy energy_label/information_list = true/false a switch=false
• vyplnit parametr ENERGY_CLASS
• zkontrolovat, zda je ve všech produktových textech (popisy/název) uvedená správná aktuální informace

Ochrana před nezamýšlenou změnou ceny produktu

V situaci, kdy partner aktualizuje produkty na různých e-shopech s rozdílnou měnou, existují určitá rizika.
Může dojít k tomu, že partner cenu produktu zašle v nesprávné měně. Abychom z části eliminovali toto riziko, je stanovena hranice pro ochranu cen produktu.
Povolený cenový rozdíl mezi starou a novou cenou produktu/varianty je 30 %.

Pokud je změna ceny produktu / varianty vyšší, než je stanovený limit, je v odpovědi vrácen force_token a produkt / varianta nejsou aktualizovány.

Produkt se značným cenovým rozdílem je tedy možné aktualizovat pouze při využití force_token získaného z neúspěšné aktualizace produktu. V dalším požadavku je nutné poslat získaný force_token jako parametr URL.

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

Aktualizací ceny produktu s pomocí force_token, partner potvrzuje, že nová cena je správná a že za tuto nově stanovenou cenu přebírá plnou odpovědnost.
V těchto případech je opatrnost na místně a není tedy vhodné používat force_token automaticky. Všechny změny a použití tokenu jsou ze strany MALL zaznamenány.
V zemích mimo CZ jako oddělovač částek používejte tečku „.“.

Příkladem:

{
  "errorCodes": [
    {
      "message": "Difference between current price ({value of current price}) and new price ({value of new price}) for product "{product id}" is larger than 30% ({real percentage difference}). To confirm this change, use attached force token.",
      "errorCode": "INCORRECT_PRODUCT_PRICE_DIFFERENCE",
      "errorAttributes": {
        "current": "currentPrice",
        "new": "newPrice",
        "id": "productId"
      }
    }
  ],
  "result": {
    "code": 400,
    "status": "ERROR",
    "message": "Difference between current price ({value of current price}) and new price ({value of new price}) for product "{product id}" is larger than 30% ({real percentage difference}). To confirm this change, use attached force token."
  },
  "data": {
    "key": "product.variants",
    "data": {
      "forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679",
      "variantIndex": 0
    }
  }
}

API endpointy

• Značky (brands) – Výpis dostupných značek.
• Kategorie – Seznam dostupných kategorií, produktových parametrů dostupných pro tyto kategorie a případně dostupné hodnoty těchto parametrů a strom MENU MALL/MIMOVRSTE.
  Potřebné údaje také naleznete v MALL Partner portálu v sekci Kategorie.
  Detailnější popis kategorií, třídících parametrů a jejich hodnot naleznete v článku zde.
• Přepravy (transports) – Seznam dopravců, kteří jsou založeni na straně MALL a jejich detail. Partner si z tohoto seznamu „vybírá“ dopravce, které bude využívat.
• Dopravy (deliveries) – Dopravy založené partnerem a zasílané zpět do MALL. Partnerem zaslané dopravy budou následně dostupné v nákupním košíku.
• Štítky (labels) – List všech dostupných štítků/nálepek. Partner využívá štítky v rámci podpory prodeje na základě pokynu ze strany MALL/MIMOVSRTE.
• Objednávky – Veškerá dostupná data o objednávkách. Obsahuje výpis všech objednávek, výpis základních dat o všech objednávkách, seznamy objednávek podle různých stavů, detail objednávky, aktualizaci objednávky, generování štítků pro MALL dopravu a další. V rámci bezpečnosti (zamezení odesílání nepřipravených objednávek partnerem) jsou z určitých výpisů záměrně odebrány objednávky ve stavu „blocked“ a je tedy třeba je volat zvlášť. Změny u objednávek je možné sledovat pomocí nástroje webhook.
• Produkty – Zakládání, editace a mazání partnerských produktů. Obsahuje výpis všech produktů, výpis základních dat o všech produktech, založení nových produktů, aktivaci „draft“ produktů, aktualizaci dostupnosti a cen produktů a další.
• Varianty – Obdobně jako produkty je možné zakládat, editovat a mazat varianty partnerských produktů.
• Ověření – Ověření konzistence dat. V možnostech je ověření doprav (deliveries) a medií.
• Faktury – Seznamy a detail faktur v případě, že partner využívá MALL Self-Billing. Možnost stáhnutí faktury jako souboru.
• Zápočty – Seznamy a detail zápočtů v případě, že partner využívá MALL Self-Billing. Možnost stáhnutí zápočtu jako souboru.