Instrukcja podłączania API

Połączenie API (MPAPI) służy do połączenia Twojego sklepu ze środowiskiem partnerskim MALL / MIMOVRSTE, czyli do wymiany informacji o produktach i ich wariantach, o ustawieniach transportu, a także do realizacji zamówień.

API oparte jest na tzw. Architekturze REST, która pozwala na dostęp do danych i wykonywanie na nich operacji, takich jak zestawianie danych, tworzenie, aktualizowanie lub usuwanie utworzonych obiektów (produkty, transport itp.).
Interfejs API korzysta z bezpiecznego połączenia HTTPS.

Do funkcjonalnego połączenia niezbędne jest uzyskanie od Partnera MALL unikalnego klucza - client_id , który służy do autoryzacji wysyłanych zapytań.

Te żądania są wysyłane do https://mpapi.mallgroup.com/ w środowisku produkcyjnym, niezależnie od kraju, w którym będziesz oferować swoje towary.
Kraj jest identyfikowany przez Identyfikator klienta.

Wszystkie dane są wysyłane i zwracane w formacie JSON i kodowaniu UTF-8. Odpowiedź na wysłane żądanie zawsze zwraca kod HTTP, w odpowiednich metodach także dane i ewentualnie również stronicowanie.

{"result": {"code": 200/400/403/404/500, "status": OK / ERROR / LIMITED, "message": dodatkowa wiadomość}, "paging": {"pages": liczba stron, "size": liczba elementów na stronę, "page": current page}, "data": {structured data}}

Szczegółowe informacje o kodach HTTP, używaniu stronicowania, a zwłaszcza o zalecanej strukturze danych, są dostępne w dokumentacji online .

Klient MPAPI jest dostępny do szybszej implementacji (obecnie obsługiwana jest tylko wersja PHP 5.5 i wyższa). Pobierz informacje i najnowszą wersję można znaleźć pod adresem packagist.org/packages/mallgroup/mpapi-client .

Changelog

Dokumentacja online zawiera aktualne informacje. Wszelkie zmiany są rejestrowane w sekcji Changelog, łącznie z datą wygaśnięcia.

Architektura API

MP API jest oparte na architekturze oprogramowania REST i zabezpieczone protokołem HTTPS .

Punkty końcowe interfejsu API

1. Przejrzyste proxy

• Przezroczysty proxy może być używany do niezależnego testowania API (możesz wywołać tryby Mock Server lub Debugging Proxy z dokumentacji online),
• Możesz śledzić swoje przezroczyste żądania proxy, klikając łącze Inspektor w górnym menu.
• jeśli nie używasz przezroczystego proxy, możesz wysyłać żądania bezpośrednio do punktów końcowych URI w środowisku produkcyjnym.

2. Środowisko produkcyjne

• Adres URL produkcyjnego interfejsu API można znaleźć pod adresem https://mpapi.mallgroup.com/v1/ , adres URL jest ważny dla każdej wersji językowej, ale dla każdego kraju obowiązuje inny identyfikator_klienta .

Upoważnienie

Każde żądanie musi zawierać klucz autoryzacyjny (identyfikator klienta). Ten klucz jest dostępny dla partnerów w portalu partnerskim.

Format danych

Wszystkie dane są w formacie JSON i zakodowane jako UTF-8 . Typ zawartości można ustawić na Content-Type: application / json lub Content-Type: application / json; Zestaw znaków = UTF-8 .

Wyjście

Dane wyjściowe mają następującą strukturę:

{"result": {"code": 200/400/403/404/500, "status": OK / ERROR / LIMITED, "message": dodatkowe informacje o błędzie}, "paging": {"pages": liczba strony, „rozmiar”: liczba obiektów na stronie, „strona”: numer bieżącej strony}, „dane”: {struktura danych}}

Żądania DELETE nie zwracają żadnej treści (kod 204).

Wynik

Wynik zwraca kod HTTP , stan i dowolny komunikat o błędzie.

Paginacja

Stronicowanie obiektów jest używane, gdy wynik jest podzielony na wiele stron.
Paging można ustawić, wywołując adres URL z parametrami page i page_size . Domyślny rozmiar strony (a także zalecane maksimum) to 100 .

Na przykład :
https://mpapi.mallgroup.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}

Dane

Struktura danych różni się w zależności od punktu końcowego i jest opisana oddzielnie dla każdego punktu końcowego w dokumentacji online .

Kody stanu HTTP

• 200 OK - wszystko w porządku, dane zwracane są poprawnie,
• 201 Utworzono - otrzymano przesłane dane i podmiot został utworzony,
• 204 Brak treści - odpowiedź na Twoje zapytanie nie zawiera żadnych danych,
• 400 Bad Request - dane przesłane przez klienta są nieprawidłowe (szczegółowy opis błędu jest zwracany w atrybucie wiadomości ),
• 401 Unauthorized - nieautoryzowany dostęp, brakujący lub zły client_id ,
• 404 Not Found - nie znaleziono wymaganych danych,
• 500 Internal Server Error - wewnętrzny błąd serwera spowodowany jest np. Brakiem dostępu do jednego z interfejsów systemu (baz danych, serwisów WWW, SAP itp.).

Funkcje API

Funkcje API są wywoływane odpowiednimi metodami HTTP :

• GET zwraca dane obiektu, nie wprowadza żadnych zmian,
• POST wysyła nowy obiekt danych,
• PUT aktualizuje istniejący obiekt danych,
• DELETE usuwa obiekt danych.

Walidacji danych

Żądania API są weryfikowane. Jeśli są jakieś błędy, które wymagają poprawienia, lista błędów jest zwracana w treści odpowiedzi.

Parametry opcjonalne

Jeśli właściwość jest opcjonalna i nie chcesz jej używać, nie umieszczaj jej w żądaniu API. Jeśli ustawisz go na pustą wartość, zostanie zwrócony komunikat o błędzie Klucz {klucz} nie istnieje lub jest pusty .

Product images (grafiki)

Aby zaktualizować zdjęcie produktu / wariantu, musisz zmienić adres URL obrazu.
Na przykład, dodając parametr w formularzu ZNAK CZASU lub Identyfikator produktu / wariantu do adresu URL obrazu.
Maksymalna rozdzielczość obrazów to 2000 pikseli x 2000 pikseli, minimalny rozmiar obrazu to 100 KB, a maksymalny to 2 MB. Maksymalna liczba zdjęć produktu to 20. Maksymalny czas odpowiedzi na adres URL obrazu to 1 s. Adres URL obrazu nie może zawierać spacji ani akcentów.

Etykieta energetyczna

Wytyczne dla nowych etykiet (Energy labels).

• należy dodać obraz etykiety energetycznej do mediów na 3-4 pozycji, obraz arkusza informacyjnego i dodać elementy energy_label/information_list = true/false i switch=false
• należy wypełnić parametr ENERGY_CLASS
• Sprawdzić, czy wszystkie teksty produktów (opisy / nazwy) zawierają prawidłowe informacje.

Ochrona przed niezamierzoną zmianą ceny produktu

W sytuacji, gdy partner aktualizuje produkty w różnych e-sklepach za pomocą różnych walut, istnieje pewne ryzyko.
Partner może przesłać cenę produktu w złej walucie. Aby częściowo wyeliminować to ryzyko, ustalono limit ochrony cen produktów.
Dopuszczalna różnica w cenie między starą a nową ceną produktu / wariantu wynosi 30 % .

Jeżeli zmiana ceny produktu / wariantu jest wyższa niż ustalony limit, w odpowiedzi zwracany jest force_token , a produkt / wariant nie są aktualizowane.

W związku z tym produkt ze znaczną różnicą cen może być aktualizowany tylko po użyciu force_token uzyskane z nieudanej aktualizacji produktu. W kolejnym zgłoszeniu konieczne jest przesłanie uzyskanego force_token jako parametr adresu URL.

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

Aktualizując cenę produktu za pomocą force_tokenPartner potwierdza, że nowa cena jest prawidłowa i bierze pełną odpowiedzialność za tę nowo ustaloną cenę.
W takich przypadkach należy zachować ostrożność lokalnie i nie należy jej stosować force_token automatycznie. Wszystkie zmiany i użycie tokena są rejestrowane przez MALL.
W krajach poza CZ użyj jako separatora kwoty kropka „.”.

Przykład:

{"errorCodes": [{"message": "Różnica między aktualną ceną ({value of current price}) a nową ceną ({value of new price}) produktu" {product id} "jest większa niż 30% ({real aby potwierdzić tę zmianę, użyj dołączonego tokenu wymuszenia. "," errorCode ":" INCORRECT_PRODUCT_PRICE_DIFFERENCE "," errorAttributes ": {" current ":" currentPrice "," new ":" newPrice "," id ": "productId"}}], "result": {"code": 400, "status": "ERROR", "message": "Różnica między aktualną ceną ({value of current price}) a nową ceną ({value of nowa cena}) dla produktu „{identyfikator produktu}” jest większa niż 30% ({rzeczywista różnica procentowa}). Aby potwierdzić tę zmianę, użyj dołączonego tokena siły. " }, "data": {"key": "product.variants", "data": {"forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679", "variantIndex": 0}}}

Punkty końcowe interfejsu API

• Marki - lista dostępnych marek.
• Kategorie / Categories - Lista dostępnych kategorii, parametry produktów dostępne dla tych kategorii i ewentualnie dostępne wartości tych parametrów oraz drzewo MENU GALERIA.
  Niezbędne dane znajdziesz również w portalu MALL Partner w dziale Kategorie / Categories.
  Bardziej szczegółowy opis kategorii, parametrów sortowania i ich wartości znajdziesz w artykule tutaj.
• Transporty - Lista przewoźników na podstawie strony MALL i ich szczegóły. Partner z tej listy „wybiera” przewoźnika, z którego będzie korzystał.
• Transport - transporty założone przez partnera i odesłane do MALL. Transport wysłany przez partnera będzie wtedy dostępny w koszyku.
• Etykiety - lista wszystkich dostępnych etykiet. Partner korzysta z etykiet w ramach wsparcia sprzedaży na podstawie instrukcji MALL / MIMOVSRTE.
• Zamówienia / Orders - Wszystkie dostępne dane dotyczące zamówień. Zawiera listę wszystkich zamówień, listę podstawowych danych o wszystkich zamówieniach, listę zamówień według różnych statusów, szczegóły zamówienia, aktualizację zamówienia, generowanie zamówienia etykiety do transportu MALL i więcej. W ramach bezpieczeństwa (zapobieganie wysyłaniu przez partnera nieprzygotowanych zamówień) zlecenia w stanie „zablokowanym” są celowo usuwane z niektórych wyciągów i dlatego muszą być wywoływane osobno. Za pomocą narzędzia można śledzić zmiany w zamówieniach webhooków.
• Produkty - tworzenie, edycja i usuwanie produktów partnerów. Zawiera listę wszystkich produktów, listę podstawowych danych o wszystkich produktach, tworzenie nowych produktów, aktywację produktów „roboczych”, aktualizację dostępności i cen produktów i nie tylko.
• Warianty - podobnie jak w przypadku produktów istnieje możliwość tworzenia, edycji i usuwania wariantów produktów partnerskich.
• Weryfikacja - weryfikacja spójności danych. Opcje obejmują weryfikację dostaw i mediów.
• Faktury - Listy i szczegóły faktur, jeśli partner używa MALL Self-Billing. Możliwość pobrania faktury do pliku.
• Kredyty - Wykazy i szczegóły kredytów, jeśli partner korzysta MALL Self-Billing. Możliwość pobrania kredytu w postaci pliku.