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

Tekst alternatywny

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 .

Identyfikacja obiektu

Wszystkie obiekty w interfejsie (np. Produkty / warianty) muszą mieć unikalny identyfikator, którym zarządza partner:

  • MALL nie przypisuje partnerom żadnych serii numerów,
  • Identyfikatory mogą zawierać maksymalnie 50 znaków, dozwolone znaki to: _ - 0-9 az AZ (podkreślenia, łączniki, cyfry od zera do dziewięciu, małe i duże litery bez akcentów).
  • Identyfikator musi być unikalny na poziomie partnera

Wyjątkami są na przykład zamówienia, wysyłka lub faktury. W przypadku zleceń MALL / MIMOVRSTE generuje order_id , który jest wtedy dostępny np. Na liście otwartych zleceń . Ten identyfikator jest numeryczny i musi być używany podczas przetwarzania zamówienia.

Ostrzeżenie :
MALL order_id przekracza maksymalny dozwolony rozmiar liczby całkowitej dla 32-bitowej wersji PHP. Aby uniknąć niespójnych danych dotyczących zamówienia, użyj wersji 64-bitowej.

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 .

Kino

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

Wskazówki dotyczące nowych etykiet energetycznych

  • 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
  • sprawdzenie, czy wszystkie teksty produktów (opisy/nazwy) zawierają prawidłowe i aktualne 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.
  • Kategoria - 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 Kategoria.
    Bardziej szczegółowy opis kategorii, parametrów sortowania i ich wartości znajduje się 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 - wszystkie dostępne dane dotyczące zamówień. Zawiera listę wszystkich zleceń, listę podstawowych danych o wszystkich zleceniach, listy zleceń według różnych statusów, szczegóły zamówienia, aktualizację zlecenia, generowanie etykiet dla transportu MALL i nie tylko. 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. Zmiany w zamówieniach można śledzić za pomocą narzędzia webhook .
  • Partnerzy - informacje ogólne i ustawienia partnerów. Zawiera ustawienia opóźnienia dostaw na poziomie całego partnera.
  • 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 w przypadku, gdy partner korzysta z samofakturowania . Możliwość pobrania faktury do pliku.
  • Kredyty - listy i szczegółowe informacje dotyczące kredytów w przypadku, gdy partner korzysta z samodzielnego rozliczania . Możliwość pobrania kredytu w postaci pliku.

Jak przydatny był ten post?

Kliknij gwiazdkę, aby ocenić post!

Średnia ocena: / 5. Liczba głosów:

Nie ma jeszcze głosów! Oceń ten post jako pierwszy.