API Media Expert (Mirakl) – automatyzacja ofert i zamówień

Przepływ zamówienia przez API krok po kroku

Najwięcej korzyści daje automatyzacja obsługi zamówień, bo od niej zależą wskaźniki jakości: terminowość wysyłek, czas uwolnienia środków i liczba incydentów. Typowy cykl wygląda następująco.

Wykres – pięć etapów obsługi zamówienia z Media Expert przez API. [#chart:me14]

1. Pobranie zamówień – system cyklicznie (np. co kilka minut) odpytuje listę zamówień i zapisuje nowe. Zamówienie po opłaceniu ma status „Oczekuje na wysyłkę” – od tego momentu liczy się czas realizacji.

2. Rezerwacja towaru – stan magazynowy w Twoim systemie zmniejsza się od razu, a nowy stan trafia do ofert na wszystkich kanałach.

3. Etykieta i numer przesyłki – etykietę tworzysz u przewoźnika lub brokera (panel Mirakl jej nie generuje), a numer listu przewozowego przekazujesz do zamówienia.

4. Potwierdzenie wysyłki – zamówienie otrzymuje status „Wysłano”. Klient dostaje link do śledzenia przesyłki.

5. Doręczenie – system platformy automatycznie śledzi obsługiwanych przewoźników i zmienia status na „Otrzymano”, co uruchamia uwolnienie środków.

6. Zwroty i anulacje – zwrot środków wykonujesz przez panel lub API; tylko wtedy prowizja wraca do sprzedawcy.

[#uwaga] Najczęstszy błąd w autorskich integracjach to brak obsługi wyjątków. Co, jeśli przewoźnik nie zwróci numeru przesyłki? Co, jeśli API odpowie błędem w trakcie aktualizacji stanów? Każdy taki przypadek powinien trafiać do logu i powiadomienia dla zespołu. Inaczej problem wyjdzie na jaw dopiero przy pogorszeniu wskaźnika opóźnionych wysyłek albo przy zamówieniu bez towaru.

Dlaczego numer przesyłki i obsługiwany przewoźnik mają takie znaczenie dla pieniędzy, wyjaśniamy w tekście o rozliczeniach przez Przelewy24. Konfigurację metod dostawy omawiamy w poradniku o wysyłce na Media Expert.

Własne API czy integrator – porównanie

Jeśli rozważasz automatyzację również na innych platformach, porównaj możliwości w tekstach o API systemu Base i REST API Allegro. Często najlepszym kompromisem jest integrator jako warstwa pośrednia, a własne skrypty tylko tam, gdzie potrzebna jest nietypowa logika.

Jak przygotować projekt integracji – checklista dla właściciela

Nawet jeśli nie piszesz kodu, to Ty odpowiadasz za decyzje biznesowe, od których zależy kształt integracji. Zanim programista zacznie pracę, ustal kilka rzeczy na piśmie.

• Źródło prawdy – który system jest nadrzędny dla stanów, cen i danych produktów.

• Częstotliwość synchronizacji – jak często aktualizować stany i pobierać zamówienia, zwłaszcza w okresach szczytu.

• Reguły cenowe – czy cena na Media Expert jest taka sama jak w sklepie, czy wyliczana z narzutem uwzględniającym prowizję.

• Obsługa przewoźników – którzy kurierzy, jakie usługi i kto generuje etykiety.

• Zwroty i anulacje – kto i gdzie je zleca, żeby prowizja wracała zgodnie z regulaminem.

• Monitoring – kto dostaje powiadomienia o błędach i w jakim czasie reaguje.

• Środowisko testowe – na czym testujecie zmiany, zanim trafią na produkcję.

[#tip] Zaplanuj integrację etapami. Najpierw automatyzuj stany i ceny oraz pobieranie zamówień, potem numery przesyłek, a dopiero na końcu tworzenie kart produktów. Każdy etap uruchamiaj na małej grupie ofert i sprawdzaj w panelu, czy dane zgadzają się z Twoim systemem.

Bezpieczeństwo i monitoring integracji

Integracja przez API działa w tle, więc jej awarie często nie są widoczne od razu. Zamówienia przestają spływać do magazynu, stany przestają się aktualizować, a zespół orientuje się dopiero wtedy, gdy klienci zaczynają pytać o przesyłki. Dlatego monitoring jest równie ważny jak sam kod.

• Log każdej operacji – zapisuj, co i kiedy zostało wysłane do API oraz jaką odpowiedź zwróciła platforma.

• Alert przy braku nowych zamówień – jeśli w godzinach, w których zwykle spływają zamówienia, przez dłuższy czas nie ma żadnego, sprawdź połączenie.

• Kontrola rozbieżności stanów – raz dziennie porównaj stany w systemie źródłowym z ofertami w panelu.

• Raporty błędów importu – po każdym imporcie ofert lub produktów odczytuj status i raport błędów, zamiast zakładać, że wszystko się udało.

• Rotacja i ochrona klucza – ogranicz dostęp do klucza i miej procedurę jego wymiany, pamiętając, że nowy klucz unieważnia stary.

• Limity zapytań – projektuj integrację tak, żeby nie odpytywała API częściej, niż to potrzebne; szczegóły limitów sprawdź w dokumentacji i u opiekuna.

Dobrą praktyką jest też panel podsumowujący dla zespołu obsługi: liczba zamówień pobranych dziś, liczba zamówień bez numeru przesyłki, ostatnia udana synchronizacja stanów. Kilka liczb na ekranie pozwala wyłapać problem w ciągu minut, a nie dni.

Przykład: producent z ERP podłącza Media Expert

[#przyklad] Producent małego AGD prowadzi magazyn i sprzedaż w systemie ERP, a stany zmieniają się w nim przez cały dzień, bo towar trafia równolegle do sieci handlowych i hurtowni. Sprzedawca nie korzysta z integratora wielokanałowego, ma za to własny zespół IT. Decyduje się na integrację przez API w trzech etapach. W pierwszym ERP co kilkanaście minut wysyła aktualne stany i ceny ofert, a w panelu pozostają tylko produkty, które już mają karty w katalogu Media Expert.

W drugim etapie integracja pobiera nowe zamówienia, tworzy w ERP dokument wydania i po wygenerowaniu etykiety u przewoźnika odsyła numer przesyłki do zamówienia. W trzecim – tworzy karty dla nowości z katalogu producenta, korzystając z mapowania kategorii i atrybutów przygotowanego na podstawie list wartości platformy. Po każdym etapie zespół przez tydzień porównuje dane w panelu z ERP. Dopiero gdy rozbieżności znikają, uruchamia kolejny etap. Taki harmonogram wydłuża wdrożenie, ale pozwala uniknąć sytuacji, w której błąd w jednym module psuje cały proces.

Najczęściej zadawane pytania

Czy Media Expert ma publiczne API dla sprzedawców?

Sprzedawcy łączą się z panelem przez Seller API platformy Mirakl, na której działa marketplace. Klucz generujesz w panelu, a według Centrum Pomocy dedykowana dokumentacja dla sprzedawców Media Expert jest w przygotowaniu.

Gdzie wygenerować klucz API?

W panelu sprzedawcy, w profilu użytkownika: Ustawienia osobiste → Klucz API. Wygenerowanie nowego klucza unieważnia poprzedni, więc zachowaj go w bezpiecznym miejscu.

Czy przez API mogę akceptować zamówienia?

Na Media Expert zamówienia są akceptowane automatycznie, więc ręczna akceptacja zwykle nie jest potrzebna. Twoja integracja powinna skupić się na pobieraniu zamówień, numerach przesyłek i potwierdzeniu wysyłki.

Czy mogę jednocześnie używać API i integratora?

Technicznie tak, ale oba systemy nie powinny aktualizować tych samych danych. Podziel odpowiedzialność jasno, np. integrator obsługuje zamówienia, a własne skrypty – ceny. Jeśli np. integrator synchronizuje stany, Twoje skrypty nie powinny ich zmieniać – inaczej dane będą się wzajemnie nadpisywać.

Czy przez API wygeneruję etykietę przewozową?

Nie przez API marketplace’u. Etykiety tworzysz u przewoźnika lub brokera, a do zamówienia przekazujesz numer przesyłki i dane śledzenia.

Ile kosztuje integracja przez API?

Media Expert nie publikuje cennika za dostęp do API. Główny koszt to praca programisty przy budowie i utrzymaniu integracji – jego wysokość zależy od zakresu automatyzacji i Twoich systemów. Do wyceny warto przygotować listę procesów, które mają zostać zautomatyzowane, oraz opis systemów, z którymi integracja ma się łączyć.

Co się stanie z integracją, gdy Mirakl zmieni API?

Zmiany w interfejsach są ogłaszane w dokumentacji i komunikatach platformy. Przy własnej integracji to Ty odpowiadasz za dostosowanie kodu, dlatego warto mieć umowę serwisową z programistą lub zespołem IT.

Podsumowanie

API Media Expert, czyli Seller API platformy Mirakl, pozwala zautomatyzować oferty, stany, ceny, zamówienia, numery przesyłek, zwroty i dokumenty. Najwięcej zyskują firmy z własnym ERP lub nietypową logiką sprzedaży; dla sprzedawców wielokanałowych prostszy bywa integrator. Kluczem do sukcesu jest jedno źródło prawdy, obsługa wyjątków i wdrażanie etapami. Aktualne informacje o integracjach znajdziesz w Centrum Pomocy dla Sprzedawców.

Wdrażamy i obsługujemy sprzedaż na marketplace’ach, w tym na Media Expert – pomożemy zaplanować integrację, przygotować specyfikację dla programisty albo dobrać integrator, a przy projektach technicznych wesprzemy Cię w ramach wsparcia informatycznego. Umów bezpłatną konsultację, a ocenimy, która droga integracji będzie dla Ciebie najbardziej opłacalna.