Jak prawidłowo podłączyć MALL Partner API

  • API

W poniższym artykule szczegółowo przedstawimy zalecany sposób łączenia różnych strumieni danych w ramach połączenia API Twojej firmy.

Środowisko testowe: Istnieje tylko jedno środowisko do testowania i realnej sprzedaży - środowisko produkcyjne. Klucz API, który otrzymasz po rejestracji, jest zatem niezmienny i ostateczny. Mimo to, można najpierw przetestować połączenie. Twoje konto jest tylko w trybie testowym, dopóki nie zostanie aktywowane. Ostateczne wyświetlenie oferty na stronie internetowej nastąpi jednak dopiero po zatwierdzeniu przez dział onboardingu, w celu uzyskania dalszych informacji prosimy o kontakt z Państwa specjalistą ds. onboardingu.

Bardzo ważne jest, aby przestrzegać poniższych zaleceń. Skutki nieprzestrzegania zalecanych praktyk mogą być ograniczające dla działania wywołań API Twojej firmy, biorąc pod uwagę obciążenie systemu MALL. Mając to na uwadze, platforma obsługuje MALL rate limiter.Więcej na ten temat można przeczytać w tutaj. Za wszelkie przekroczenia SLA spowodowane nieprawidłową implementacją API oraz przekroczenia limitu stawek odpowiada partner

Należy pamiętać, że API MALL jest źródłem bieżących informacji, nie jest bazą danych, która byłaby używana do przechowywania danych historycznych. Wywołania API o takim charakterze mogą być ograniczone.

Używasz identyfikatora klienta, lub "klucza API", aby autoryzować wszystkie wywołania API w ramach połączenia MALL. Klucz API ma kombinację znaków, które są unikalne dla każdego konta i muszą być dołączone do każdego indywidualnego wywołania API. Jeśli masz wiele kont na MALL, klucz będzie unikalny dla każdego konta. Klucz API można znaleźć w Portalu Partnerskim MALL w sekcji "Profil firmy" w zakładce "Informacje".

Spis treści

Zamówienia / Orders

Podczas pracy z endpointami dla zamówień należy zwrócić szczególną uwagę na kolejność kroków. Dzieli się ona na dwie podstawowe opcje w zależności od tego, czy korzystasz z webhooków do pozyskiwania informacji o zmianach w zamówieniach. Więcej na temat webhooków możesz przeczytać tutaj.

W tym artykule dowiesz się jak poprawnie powiązać poszczególne metody i przełączać poszczególne statusy w ramach API. Polecamy także przeczytanie artykułu wyjaśniającego znaczenie poszczególnych statusów zamówień, informacje dostępne są tutaj.

Zwróć uwagę: jeśli korzystasz z usług MALL Delivery, proces różni się w późniejszych etapach wysyłki zamówienia i aktualizacji statusu.

Ważne: aktualizacje statusu zamówienia wysyłaj tylko w przypadku faktycznej zmian w zamówieniach. Wielokrotne wysyłanie tych samych informacji jest wysoce niepożądane i uciążliwe dla systemu.

Sekwencja wywołań zamówień z wykorzystaniem webhooka

Po pierwsze, należy włączyć webhook i wstawić przygotowany adres URL do odpowiedniej zakładki w portalu partnerskim w menu Partner, a następnie można zobaczyć poszczególne powiadomienia wychodzące w dzienniku.

1. Otrzymujesz powiadomienie webhooka z numerem zamówienia, dla którego nastąpiła zmiana.

2. Użyj wywołania API Get order detail dla zamówień o statusie BLOCKED do rezerwacji towarów. Są to zlecenia, dla których otrzymałeś pierwsze powiadomienie. Prosimy tylko o informacje na temat towaru. Otrzymywanie informacji finansowych tylko dla zamówień o statusie OPEN. Rezerwacja towarów nie jest obowiązkowa, ale jest zalecana dla towarów o wysokiej sprzedawalności i związanym z tym ryzykiem wyprzedaży.

3. Otrzymujesz powiadomienie webhook dla zamówień, których status zmienił się na OPEN lub CANCELED.

4. Użyj wywołania API Update order z potwierdzone = prawda dla OPEN lub CANCELED zleceń, które zostały zmienione zgodnie z informacją z webhooka. Możliwa zmiana statusu z BLOCKED na OPEN lub CANCELED (jest to stan końcowy i ponowne otwarcie zamówienia nie jest już możliwe).

5. Użyj wywołania API Get order detail dla zamówień z kroku 4., dla zamówień CANCELED anuluj rezerwację. Dla zamówień OPEN zamówień, użyj wywołania na potwierdzonych zamówieniach, aby zaimportować ostateczne dane do swojego systemu. W tym momencie nie ma już możliwości ingerencji z żadnej strony w zamówienie, więc wszystkie informacje takie jak adres i kwota za pobraniem są w tym momencie ostateczne.

6. Użyj wywołania API Update order dla zamówień zmieniających status z OPEN na SHIPPING które są w procesie wysyłki. Jeśli pojawią się okoliczności, które uniemożliwią wysłanie zamówienia, możliwa jest zmiana statusu zamówienia na CANCELED.

7a. W przypadku korzystania z usługi MALL Delivery, użyj wywołania API Generate labels for selected MDP orders do drukowania etykiet dla zamówień MALL Delivery.

7b. Jeśli nie korzystasz z usługi MALL Delivery, musisz spełnić wymagania dotyczące wysyłki określone przez Twojego przewoźnika.

8. Przekazanie przesyłki firmie transportowej.

9a. W przypadku korzystania z usługi MALL Delivery należy skorzystać z wywołania Update order dla zamówień zmieniających status z SHIPPING na SHIPPED (zmiana statusu na SHIPPED musi nastąpić zawsze po przekazaniu przesyłki kurierowi).

9b. Jeśli nie korzystasz z usługi MALL Delivery, użyj wywołania Update order dla zamówień zmieniających status z SHIPPING na SHIPPED, w tym adres URL śledzenia i numer przesyłki przewoźnika. Wszystkie informacje muszą zostać wysłane w jednym wywołaniu,aby spełnić kryteria jakości usług – Tracking rate.

Opcjonalny: Korzystając z MALL Delivery, możesz zadzwonić na podstawie powiadomienia webhook o zmianie w zamówieniu POBIERZ szczegóły zamówienia dla zamówień w stanie DOSTARCZONE / ZWRÓCONE / ZGUBIONEw celu nadania ostatecznego statusu zamówieniom w Państwa systemie.

10. Jeśli nie korzystasz z usługi MALL Delivery, użyj wywołania API Update order dla zamówień zmieniających status z SHIPPED na DELIVERED z dokładną datą dostawy na podstawie informacji uzyskanych od przewoźnika. Jeśli posiadasz informacje od przewoźnika o pierwszej próbie doręczenia, możesz je również dodać, ale są one opcjonalne. Aktualizacja musi być przesłana w jednym wywołaniu.Jeśli zamówienie nie mogło zostać dostarczone i zostało zwrócone do nadawcy, zmień status zamówienia z SHIPPED na RETURNED.

SLA i zadowolenie klientów: Niezależnie od wybranej formy łączenia zleceń ważne jest, aby ustalanie statusów zleceń opierało się na stanie faktycznym i było jak najbardziej aktualne. Wpływa to na zadowolenie klientów, a także stanowi końcowe SLA. Nieprawidłowa realizacja nadawania statusów może prowadzić do negatywnych doświadczeń klientów i anulowania zamówień.

Sekwencja wywoływania zamówień bez użycia webhooka

1. Używaj wywołania API Get list of unconfirmed orders z regularną częstotliwością. Zalecamy dostosowanie częstotliwości do średniej liczby zamówień. Stosuj wywołania częściej niż raz na godzinę tylko dla ponad 100 zamówień dziennie. Przy wywołaniu użyj filtr = basic.

2. Na podstawie List of unconfirmed orders wywołaj funkcję Get order detail dla zamówień o statusie BLOCKED , aby zarezerwować towar. Przejmij tylko informacje o towarach. Pozyskaj informacje finansowe tylko dla zamówień w statusie OPEN. Rezerwacja towarów nie jest obowiązkowa, ale jest zalecana dla towarów o wysokiej sprzedawalności i związanym z tym ryzykiem wyprzedaży.

3. Użyj wywołania API Update order z potwierdzone = prawda dla OPEN/CANCELED zlecenia, które zostały zarejestrowane przez Twój system w wywołaniu.

4. Użyj wywołania API Get order detail na OPEN potwierdzone zamówienia, aby zaimportować ostateczne dane do swojego systemu. W tym momencie nie ma już możliwości ingerencji w zamówienie z jakiejkolwiek strony, wszystkie informacje takie jak adres i kwota za pobraniem są w tym momencie ostateczne.

5. Użyj wywołania API Update order dla zamówień zmieniających status z OPEN na SHIPPING które są w procesie wysyłki. Jeśli pojawią się okoliczności, które uniemożliwią wysłanie zamówienia, możliwa jest zmiana statusu zamówienia na CANCELED.

6a. W przypadku korzystania z usługi MALL Delivery, użyj wywołania API Generate labels for selected MDP orders do drukowania etykiet dla zamówień MALL Delivery.

6b. Jeśli nie korzystasz z usługi MALL Delivery, musisz spełnić wymagania dotyczące wysyłki określone przez Twojego przewoźnika.

Rekomendujemy sprawdzenie statusu zamówienia przed jego wysłaniem. W statusie SHIPPING zamówienie może zostać anulowane przez klienta. Takie zamówienie zostanie wówczas zmienione przez system na status CANCELED. Zmiana ta będzie również widoczna na liście Get list of unconfirmed orders i wymaga potwierdzenia poprzez zastosowanie kroku 3.

7. Dostarczenie przesyłki do firmy transportowej.

8a. W przypadku korzystania z usługi MALL Delivery, użyj wywołania API Update order dla zamówień zmieniających status z SHIPPING na SHIPPED (zmiana statusu na SHIPPED musi nastąpić zawsze po przekazaniu przesyłki kurierowi).

8b. Jeśli nie korzystasz z usługi MALL Delivery, użyj wywołania Update order dla zamówień zmieniających status z SHIPPING na SHIPPED, w tym adres URL śledzenia i numer przesyłki przewoźnika. Wszystkie informacje muszą być przesłane w jednym połączeniu, aby spełnić kryteria jakości usługi - Tracking rate.

Opcjonalny: Możesz korzystać z połączeń podczas korzystania z dostawy MALL Pobierz listę zamówień według statusu używanie filtra czasu dla DOSTARCZONE / ZWRÓCONE / ZGUBIONE zamówień w celu nadania ostatecznego statusu zamówieniom w Twoim systemie.

9. Jeśli nie korzystasz z usługi MALL Delivery, użyj wywołania Update order dla zamówień zmieniających status z SHIPPED na DELIVERED z dokładną datą dostawy na podstawie informacji uzyskanych od przewoźnika. Jeśli posiadasz informacje od przewoźnika o pierwszej próbie doręczenia, możesz je również dodać, ale są one opcjonalne. Aktualizacja musi być przesłana w jednym wywołaniu.Jeśli zamówienie nie mogło zostać dostarczone i zostało zwrócone do nadawcy, zmień status zamówienia z SHIPPED na RETURNED.

Wsteczna walidacja danych: W przypadku konieczności pobrania danych zamówienia, zawsze wywołuj poszczególne zamówienia, których dane są Ci potrzebne. Jeśli mimo to konieczne jest wywołanie listy zleceń, należy użyć filtry przedziałów czasowych i uniknąć wywoływania całej historii zamówień naraz. Do celów rozliczeniowych i fakturowania podczas korzystania z usługi MALL Self-Billing, użyj endpointów.

Powrót do góry

Produkty / Products

W przypadku produktów, musisz skupić się na dwóch rodzajach połączeń, tworzeniu produktów i ich aktualizacji.

Tworzenie produktów i wariantów

Przy tworzeniu produktu zawsze zwracaj uwagę na nasze warunki dotyczące zawartości produktu, szczegóły znajdziesz tutaj. Następnie dokładnie zapoznaj się z warunki wyświetlania produktów w poszczególnych kategoriach w artykule tutaj w celu uniknięcia konieczności wprowadzania poprawek do produktu poprzez kolejne wywołania.

Ważne: Jeśli Twoje produkty posiadają warianty, zawsze twórz warianty produktów w oparciu o parametry dostępne w kategorii. Zgłaszanie wariantów produktów jako indywidualnych ofert jest niepożądane i może doprowadzić do usunięcia oferty z serwisu.

Produkty bez wariantów są tworzone przez wywołanie API Create new productJeśli wystąpi błąd przy tym połączeniu, przygotowaliśmy artykuł wyjaśniający poszczególne błędy oraz sposoby ich zapobiegania i korygowania. Artykuł można znaleźć pod linkiem tutajStruktura wywołania jest obowiązkowa z wyjątkiem elementów, gdzie jest to wyraźnie zaznaczone w dokumentacji. Utworzony w ten sposób produkt można następnie znaleźć na liście produktów w portalu, a także na stronie na liście produktów, gdzie można go zobaczyć korzystając z konta sandbox.

W przypadku produktów wariantowych, najpierw użyj wywołania Create new product w celu stworzenia produktu głównego. Następnie dodaj warianty do tego produktu za pomocą Create new variant. Warianty muszą być rozróżniane za pomocą parametrów wariantu. Możesz użyć maksymalnie dwóch parametrów z dostępnych w danej kategorii. Warianty przypisane do produktu głównego są zawsze wyświetlane na szczegółach produktu z odpowiednim parametrem jako zmienną do wyboru przez klienta.

Dla produktów wypełnij priorytet z 1. System automatycznie szereguje produkty za pomocą algorytmu, który działa na podstawie liczby kliknięć, ruchu i sprzedaży danego produktu. 
Jest to przestarzały element, który nadal wymaga wypełnienia, ale nie jest w ogóle brany pod uwagę. Obecnie pracujemy nad jego usunięciem.

W przypadku produktów ważne jest, aby wskazać EAN (GTIN)ma ściśle określony kształt - 13 znaków numerycznych. EAN ma duży wpływ na dopasowanie produktów w Google Ads, Heureka i Zboží.cz, a tym samym na możliwość dotarcia z Państwa produktami do większej ilości klientów.
Jeśli EAN składa się z 14 znaków numerycznych, wpisz 13 cyfr bez 0 na początku. W przypadku krótszego, 8-cyfrowego numeru EAN, należy dodać na początku tyle 0, ile brakuje do 13 znaków (5)..

Aktualizacja produktów

W przypadku produktów aktualizację dzielimy na kilka rodzajów:

  • Aktualizacja danych produktów (etykiety, zdjęcia, parametry, itd.)
  • Aktualizacja cen
  • Aktualizacja dostępności

Ważne: Wysyłaj wszelkie aktualizacje produktów tylko w przypadku zmian. Wielokrotne wysyłanie tych samych informacji jest wysoce niepożądane i uciążliwe dla platformy.

Aktualizacja danych produktu

Podczas aktualizacji danych produktu, użyj odpowiedniej metody UPDATE produkt główny lub wariant. Zmieniaj dane tylko wtedy, gdy ulegną one zmianie lub gdy trzeba je dodać. Dokonując jakiejkolwiek aktualizacji produktu należy zawsze wysyłać wszystkie elementy, a nie tylko te, które uległy zmianie.

Aktualizacja cen

W celu zaktualizowana ceny, nie należy używać metody aktualizacji produktu lub wariantu opisanej powyżej.Do zmiany ceny udostępnione zostało osobne wywołanie, za pomocą którego można wysłać zmianę, zarówno dla produktu głównego, jak i dla wariantów. W przypadku aktualizacji ceny o więcej niż 30%, zmiana ceny musi być potwierdzona za pomocą token force. Więcej informacji na temat tej funkcji znajdziesz w naszej dokumentacji tutaj.

Aktualizacja dostępności

W celu zaktualizowana dostępności, nie należy używać metody aktualizacji produktu lub wariantu opisanej powyżej. Aby zmienić dostępność, użyj metody masowej zmiany dostępności produktu poprzez Batch update of product/variant availability. Prosimy o jak najczęstsze korzystanie z tej opcji, za pomocą aktualizacji zbiorczej można zaktualizować do 1000 produktów/wariantów jednocześnie.

w przypadku konieczności zmiany liczby produktów, możliwe jest użycie metody aktualizacji dostępności magazynowej produkt lub wariantów.

Wsteczna walidacja danych: Jeśli istnieje przypadek, w którym musisz odzyskać dane o produkcie, dzwoń do nich tylko wtedy, gdy jest to konieczne i tylko przez odpowiedni punkt końcowy dla ceny lub dostępności. Wszelkie okresowe masowe lub indywidualne wezwania do podania danych produktowych są wysoce niepożądane i uciążliwe dla naszego systemu i mogą skutkować ograniczeniem Twojego połączenia z MALL.

Powrót do góry

Batch endpoints

W ramach MALL API, niektóre akcje mogą być wykonywane przez masowe zmiany. Używanie wsadowych punktów końcowych znacznie zmniejszy wykorzystanie limitu wywołań API w ograniczniku, więc zaleca się używanie ich tak często, jak to możliwe.

Dostępne batch endpoints:

  • Batch availability update - Jak opisano powyżej w przypadku aktualizacji dostępności, jest to zbiorcza aktualizacja dostępności produktów i wariantów. Ta metoda pozwala zaktualizować do 1000 zmian w jednym wywołaniu.
  • Active selected products - Masowa zmiana wybranych produktów z wersji roboczej na live.
  • Activate products - Masowa zmiana wszystkich produktów z wersji roboczej na live.

Dezaktywacja i usuwanie produktów

Istnieje kilka metod, których możesz użyć, aby ukryć produkt z sieci, w zależności od powodu, dla którego chcesz go usunąć.

  • Produkt jest tymczasowo wyprzedany, będzie ponownie dostępny - w tym przypadku w ramach aktualizacji dostępności produktu wystarczy zmniejszyć dostępność magazynową produktu do „0”, nie będzie wtedy możliwości zakupu produktu na stronie, ale klienci nadal będą mogli oglądać produkt, sprawdzając jego dostępność.
  • Tymczasowa potrzeba usunięcia produktu ze strony - aktualizując dostępność produktu, można skorzystać z pola status, w którym ustawienie wartości „N” spowoduje, że produkt lub wariant stanie się „nieaktywny”.
  • Usunięcie produktu - jeśli wiadomo, że produktu lub wariantu nie będzie w magazynie dłużej niż 2 miesiące, zalecamy usunąć produkt lub wariant usunąć poprzez odpowiedni punkt końcowy. MALL utrzymuje historyczne dane sprzedaży dla Twoich produktów, jeśli załadujesz produkt pod tym samym ID, dane sprzedaży zostaną ponownie sparowane.

Ważne: Nie aktualizuj produktów nieaktywnych. Wielokrotne wysyłanie aktualizacji dla nieaktywnych produktów jest wysoce niepożądane i uciążliwe dla platformy. Kiedy limit zostanie przekroczony, system może zostać przeciążony i będzie akceptował tylko częściowe dane, co może wpłynąć negatywnie na doświadczenia klienta, jak również potencjalną stratę po stronie partnera.

Powrót do góry

Kategorie / Categories

W ramach naszego API, użyj dwóch podstawowych punktów końcowych, aby pobrać dane kategorii. W pierwszym z nich Category tree by country otrzymasz drzewo kategorii dostępne dla danego kraju. Zmieniając kod kraju w adresie URL wywołania, można następnie uzyskać informacje o drzewach kategorii dla innych krajów przy użyciu tego samego klucza API.

Wynikiem wywołania API jest zawsze kilka fragmentów danych, które są niezbędne dla Twojej integracji.

  • menu item ID (="menuItemId") - unikalny kod kategorii, który możesz wykorzystać do wywołania Category Detail aby uzyskać listę wszystkich parametrów i wartości, wywołanie jest opisane poniżej.
  • Product Type ID (= "ProductTypeId") - kod kategorii technicznej potrzebny do sklasyfikowania produktu, kod ten może być zgodny z wieloma menuitemID.
  • Menu Constraints (= "MenuCosntraints") - obowiązkowe parametry z wartościami potrzebnymi do przypisania produktów do danego menuitemID. Szczegółowy artykuł o szczegółach warunków kategorii można przeczytać tutaj.

Weryfikacja prawidłowego wyświetlania na stronie internetowej: Produkt, który wgrałeś do systemu, a który nie spełnia warunków Menu Constraints, może pokazać błąd przy wyświetlaniu, a tym samym nie będzie dostępny dla klientów.

Poprzez wywołanie API Category detail wtedy otrzymamy listę danych. Pierwsza część zawiera warunki wyświetlania dla danej kategorii.

  • SAP ID (= "SapId") - kod techniczny kategorii, to ten sam kod, który został podany w poprzednim wywołaniu jako Product Type ID, jest to kod techniczny kategorii potrzebny do sklasyfikowania produktu.
  • Category Conditions (= "CategoryConditions") tutaj znajdują się te same dane co w Menu Constraints w poprzednim wywołaniu. Aby umieścić produkt w dowolnej kategorii, należy zawsze poprawnie wpisać te warunki.

Weryfikacja prawidłowego wyświetlania na stronie internetowej: Produkt, który wgrałeś do systemu, a który nie spełnia warunków Menu Constraints, może pokazać błąd przy wyświetlaniu, a tym samym nie będzie dostępny dla klientów.

  • Other parameters (= "OtherParameters"): Tutaj znajdziesz wszystkie inne parametry z wartościami, które mogą być użyte i dodane do Twoich produktów. W przypadku parametrów należy zawsze korzystać z listy wartości, które znajdują się tutaj, wprowadzanie własnych wartości do parametrów nie jest możliwe. Zawsze dodawaj nazwę parametrów do produktu w nazwach technicznych, w polu Wartość. Zawsze wpisuj wartości w nazwie docelowego kraju sprzedaży, czyli wartości z pola "tekst". W przypadku wartości liczbowych zawsze używaj jednostki podanej w polu Jednostka. Jeśli parametr nie zawiera wartości, których potrzebujesz, wyślij do nas zapytanie poprzez Centrum Pomocy.

Powrót do góry

Brands (marki)

Używając wywołania API Get all brands otrzymasz pełną listę dostępnych marek we wszystkich krajach. Lista nie jest unikalna dla każdego kraju, więc możesz jej użyć, aby połączyć się z dowolnym rynkiem partnerskim MALL. Zawsze dodawaj dane z pola „brand_id” do produktów w dopasowaniu 100%, w tym wielkie litery.

Aby dodać brand, użyj odpowiedniej zakładki w portalu partnerskim, zgodnie z instrukcjami tutaj.

Labels (etykiety)

Używając wywołania API Pobierz wszystkie etykiety zawsze otrzymasz pełną listę etykiet w naszej bazie danych. Etykiety są wykorzystywane w kampaniach marketingowych i innych procesach wewnętrznych. Używanie tych etykiet jest niedozwolone bez uprzedniej zgody przedstawiciela handlowego w firmie MALL.

  • FDEL - bezpłatna dostawa
  • SALE - wyprzedaż
  • NEW - nowy

Powrót do góry

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.

Otagowano: