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 do właściwej sprzedaży, to środowisko produkcyjne. Klucz API, który otrzymujesz po rejestracji jest niezmienny i ostateczny. Niemniej jednak, połączenie może być najpierw przetestowane. Twoje konto jest w trybie testowym, dopóki nie zostanie aktywowane. Ostateczne wyświetlenie twojej oferty na stronie internetowej nastąpi dopiero po zatwierdzeniu przez dział onboardingu. Aby uzyskać więcej informacji, skontaktuj się ze swoim specjalistą ds. onboardingu.

Należy przestrzegać poniższych zaleceń. Nie zastosowanie się do zalecanych kroków może skutkować ograniczonym funkcjonowaniem wywołań API Państwa firmy, z uwagi na obciążenie systemu MALL. Mając to na uwadze, platforma działa w oparciu o 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.


Spis treści


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

W pierwszej kolejności należy włączyć webhook i wstawić adres URL do odpowiedniej zakładki w portalu partnerskim w menu „Partner”, następnie w logu będą pojawiać się poszczególne powiadomienia wychodzące.

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 , aby zarezerwować towar. Są to zamówienia, dla których otrzymałeś pierwsze powiadomienie. Przejmij tylko informacje o towarach. Informacje finansowe pozyskaj 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 confirmed = true dla zamówień w statusie OPEN lub CANCELLED, których status został zmieniony zgodnie z informacją webhook. Możliwa jest zmiana statusu z BLOCKED na OPEN lub CANCELLED (jest to status ostateczny i zlecenie nie może być ponownie otwarte).

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, konieczne jest spełnienie warunków wysyłki określonych przez 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.

Opcjonalnie: W przypadku korzystania z usługi MALL Delivery, możesz wywołać funkcję Get order detail dla zamówień o statusie DELIVERED/RETURNED/LOST, w celu zaktualizowania końcowego statusu zamówienia w Twoim 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 od przewoźnika. Jeśli posiadasz informacje od przewoźnika o pierwszej próbie doręczenia, również można ją dodać, jest to informacja opcjonalna. 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 confirmed = true dla zamówień o statusie OPEN/CANCELLED, które zostały zarejestrowane przez Twój system w wywołaniu.

4. Użyj wywołania API Get order detail dla potwierdzonych zleceń o statusie OPEN , aby zaimportować końcowe dane do systemu. W tym momencie nie jest już możliwa żadna ingerencja w zamówienie, więc wszystkie informacje takie jak adres i kwota pobrania są 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, konieczne jest spełnienie warunków wysyłki określonych przez 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.

Opcjonalnie: W przypadku korzystania z usługi MALL Delivery, możesz wywołać funkcję Get order detail dla zamówień o statusie DELIVERED/RETURNED/LOST, w celu zaktualizowania końcowego statusu zamówienia w Twoim systemie.

9. 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 od przewoźnika. Jeśli posiadasz informacje od przewoźnika o pierwszej próbie doręczenia, również można ją dodać, jest to informacja opcjonalna. Aktualizacja musi być wysłana w jednym telefonie. Jeśli zamówienie nie zostało 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 unikając wywoływania całej historii zleceń na raz. Do celów rozliczeniowych i fakturowania przy korzystaniu z usługi samofakturowania należy użyć odpowiednich endpointów.

Powrót do góry


Produkty

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 produkty wariantowe w oparciu o parametry dostępne w danej kategorii. Wysyłanie produktów wariantowych jako pojedynczych rekordów jest niepożądane i może doprowadzić do usunięcia Twoich produktów ze strony.

Produkty bez wariantów są tworzone przez wywołanie API Create new product. W przypadku wystąpienia błędu przy tym wywołaniu, przygotowaliśmy artykuł wyjaśniający poszczególne błędy oraz możliwy sposób ich zapobiegania i korygowania. Artykuł ten można znaleźć 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.

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 regularne masowe lub indywidualne wezwania do podania danych produktów są wysoce niepożądane i uciążliwe dla naszego systemu i mogą prowadzić do ograniczenia Twojego połączenia z MALL.

Powrót do góry

Batch endpoints

W ramach API MALL, niektóre działania mogą być wykonywane masowo. Używając Batch endpoints, znacznie zmniejszysz wykorzystanie swojego limitu wywołań API w ramach rate limitera, w związku z tym zaleca się korzystanie z nich tak często, jak to możliwe.

Dostępne batch endpoints:

  • Batch availability update - zgodnie z opisem powyżej, jest to masowa aktualizacja dostępności produktów i wariantów. Ta metoda pozwala na aktualizację do 1000 zmian w jednym wywołaniu.
  • Active selected products - masowa zmiana wybranych produktów z wersji roboczej na produkcyjną.
  • Activate products - masowa zmiana wszystkich produktów z wersji roboczej na produkcyjną.

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 poprzez odpowiedni endpoint. MALL przechowuje dane historii sprzedaży Twoich produktów, więc jeśli wrzucisz produkt później 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


„Categories”

W ramach naszego API możesz skorzystać z dwóch podstawowych endpointów do pobierania danych o kategoriach. W pierwszym z nich Category tree by country otrzymujesz drzewo kategorii dostępne dla konkretnego kraju. Zmieniając kod kraju w adresie URL wywołania, możesz uzyskać informacje o drzewach kategorii innych krajów, używając tego samego klucza API.

Wynikiem wywołania API są zawsze dane niezbędne do 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 otrzymasz listę danych. Pierwsza część zawiera warunki wyświetlania w 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ę parametru do produktu w polu nazw technicznych, pole Wartość. Zawsze wpisuj wartości w nazwie kraju docelowego sprzedaży, czyli wartości z pola "tekst". W przypadku wartości numerycznych należy zawsze używać jednostki określonej w 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 kompletną listę dostępnych marek we wszystkich krajach. Lista ta nie jest unikalna dla każdego kraju, więc możesz jej użyć do połączenia z dowolnym rynkiem MALL Partner. Zawsze dodawaj „brand_id” do produktów w niezmienionej formie, uwzględniając także wielkość liter.

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 otrzymasz pełną listę etykiet znajdujących się w naszej bazie danych. Etykiety są wykorzystywane w kampaniach marketingowych i innych procesach wewnętrznych. Etykiety mogą być używane bez wcześniejszej zgody przedstawiciela handlowego 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.