API Empik Place – co można zautomatyzować w ofertach i zamówieniach

Oferty przez API – ceny, stany i czasy wysyłki

Oferty tworzysz i aktualizujesz, przesyłając plik ofertowy przez API OF01 lub OF24. Najczęściej używane pola to identyfikator oferty (sku), identyfikator produktu i jego typ (np. EAN), cena, stan magazynowy, stan produktu (11 oznacza produkt nowy), klasa logistyczna i czas do wysyłki (leadtime-to-ship). Po imporcie pobierasz raport OF03 i sprawdzasz kolumnę z komunikatami błędów.

• Cena – w formacie z kropką dziesiętną, np. 42.53; cena promocyjna z datami rozpoczęcia i zakończenia.

• Stan – aktualizowany tak często, jak wymaga tego tempo sprzedaży w Twoich kanałach.

• Czas wysyłki – wartość w dniach roboczych; integracja nadpisuje wartości ustawione ręcznie w panelu.

• Klasa logistyczna – decyduje o dostępnych formach dostawy i cenach dla klienta.

Jeśli oferta odnosi się do produktu, którego nie ma w katalogu Empiku, import zwróci błąd i trzeba najpierw założyć kartę produktu. Typowe komunikaty i sposób ich naprawy opisujemy w artykule o błędach importu na Empik Place.

Produkty przez API – nowe karty w katalogu

Developer Portal opisuje dwie ścieżki zakładania nowych kart produktów. W pierwszej pobierasz strukturę kategorii (H11), konfigurację atrybutów (PM11) i listy wartości (VL11), przypisujesz je do swoich produktów i przesyłasz plik produktowy przez P41, a wynik weryfikujesz raportem. W drugiej mapujesz własną strukturę pliku w kreatorze konfiguracji w panelu, a potem ustawiasz cykliczne importy przez P41 – pliki o tej samej strukturze będą odczytywane automatycznie.

[#uwaga] Jeśli w Twoim pliku pojawi się nowa kategoria, nowy atrybut albo nowa wartość słownikowa, mapowanie trzeba uzupełnić – ale tylko dla nowych elementów, bo dotychczasowe zostaje zapisane. Pamiętaj też, że karty produktów weryfikuje Empik i tylko Empik może je edytować, a nowe karty należy zgłaszać z materiałami co najmniej 5 dni przed planowaną prezentacją. Zasady przypisywania kategorii opisujemy w tekście o kategoriach i atrybutach na Empik Place.

Zamówienia przez API – od akceptacji do zamknięcia

API pozwala obsłużyć zamówienie od momentu jego złożenia do zamknięcia, łącznie z przekazaniem numeru listu przewozowego. Workflow różni się nieco dla płatności z góry i za pobraniem – przy pobraniu po akceptacji zamówienie od razu przechodzi do realizacji. Kolejne statusy zamówienia z płatnością z góry pokazuje wykres. [#chart:em48b]

Zgodnie z regulaminem zamówienie trzeba przyjąć lub odrzucić maksymalnie w ciągu 3 dni, a standard jakości wymaga średniego czasu akceptacji do 12 godzin w okresie 90 dni. Status Otrzymano jest nadawany automatycznie, jeśli przy zmianie statusu na Wysłano podasz numer listu przewozowego zintegrowanego przewoźnika – Developer Portal wymienia m.in. InPost, DPD, UPS, DHL, Pocztę Polską i FedEx. Zamówienie zamyka się 60 dni po statusie Otrzymano, a zwroty i incydenty są możliwe w statusach od wysyłki w trakcie realizacji do otrzymania.

Szczegóły statusów i ich wpływu na wskaźniki opisujemy w artykule o czasie realizacji zamówień na Empiku, a automatyzację statusów, faktur i numerów przesyłek – w tekście o Empik Place bez ręcznej pracy.

Zasady techniczne i limity API

Developer Portal opisuje kilka zasad, których przestrzeganie zapewnia stabilność integracji przy kolejnych zmianach po stronie Empiku:

[#tip] Projektując integrację, od początku obsłuż błąd 429 i nagłówek Retry-After oraz nie zakładaj stałej kolejności pól w odpowiedziach. To najczęstsze przyczyny integracji, które działają w testach, a zawodzą w szczycie sezonu, gdy liczba zamówień i aktualizacji gwałtownie rośnie.

Środowisko testowe

Empik udostępnia bezpłatne środowisko testowe, w którym konto zakłada się przez formularz. Pozwala ono poznać panel Empik Marketplace, podstawowe procesy sprzedażowe, dodawać testowe oferty i produkty oraz konfigurować panel. Zamówienia testowe mogą składać tylko pracownicy Empik Marketplace – jeśli chcesz przetestować obsługę zamówień, trzeba skontaktować się z supportem przez formularz kontaktowy. W formularzu rejestracyjnym środowiska testowego nie należy podawać prawdziwych danych osobowych.

Kiedy własna integracja przez API ma sens

Własna integracja to inwestycja w development i utrzymanie. Warto ją rozważyć, gdy:

• masz własny system ERP lub WMS, z którym gotowe integracje nie współpracują,

• obsługujesz kilka magazynów lub niestandardowe reguły dostępności,

• potrzebujesz specyficznych reguł cenowych, np. dynamicznej wyceny dla Empiku,

• chcesz zautomatyzować obsługę wiadomości lub dokumentów w sposób, którego nie oferują gotowe narzędzia,

• skala sprzedaży uzasadnia koszt własnego rozwiązania.

W pozostałych przypadkach szybszym i tańszym rozwiązaniem jest zwykle system wielokanałowy, który korzysta z API Empiku za Ciebie. Integrację Empiku w Base opisujemy w artykule BaseLinker Empik – jak sprzedawać przez Base.

[#przyklad] Hurtownia papiernicza z własnym ERP sprzedaje na Empiku 8000 produktów. Gotowe integracje nie obsługują jej podziału na trzy magazyny, więc zespół IT buduje połączenie z API: co kilkanaście minut wysyła lekki plik ofertowy tylko ze zmianami stanów, co kilka minut pobiera nowe zamówienia, automatycznie je akceptuje po sprawdzeniu dostępności w ERP i przekazuje numery listów przewozowych z systemu kurierskiego. Wcześniej wszystkie scenariusze testuje w środowisku testowym (przykład).

Najczęstsze błędy przy integracji przez API

• Brak obsługi limitów i błędu 429 – integracja przestaje działać przy większym ruchu.

• Wysyłanie pełnych plików ofertowych przy każdej zmianie stanu zamiast lekkich aktualizacji.

• Ignorowanie raportów błędów OF03 i P44 – część ofert i produktów nigdy nie trafia do sprzedaży.

• Automatyczna akceptacja zamówień bez sprawdzenia dostępności towaru.

• Zmiana statusu na Wysłano bez numeru listu przewozowego.

• Zakładanie stałej struktury odpowiedzi API, co psuje integrację po aktualizacji interfejsu.

Wszystkie te błędy przekładają się na wskaźniki jakości: odrzucone zamówienia, opóźnienia i incydenty. Dlatego integracja przez API powinna mieć monitoring i alerty – informację o błędach importu, nieprzetworzonych zamówieniach i przekroczonych limitach. Jak pilnować progów, wyjaśniamy w artykule o wskaźnikach jakości na Empik Place. O synchronizacji stanów przeczytasz w tekście o synchronizacji stanów i cen.

Najczęściej zadawane pytania

Jak wygenerować klucz API w Empik Place?

Zaloguj się do Panelu Sprzedawcy, kliknij swoją nazwę użytkownika w prawym górnym rogu, przejdź do zakładki Klucz API i kliknij Wygeneruj nowy klucz. Klucz możesz skopiować do schowka i wkleić w konfiguracji integracji.

Gdzie znajdę dokumentację API Empiku?

Zasady ogólne, przykłady plików i workflow zamówień opisuje Developer Portal w Centrum Pomocy Empik Place. Szczegółowa dokumentacja API Mirakl jest dostępna po zalogowaniu do panelu.

Czy przez API można zakładać nowe karty produktów?

Tak. Możesz pobrać kategorie, atrybuty i wartości, a następnie przesłać plik produktowy przez P41 albo zmapować własny plik w kreatorze i ustawić cykliczne importy. Karty weryfikuje i edytuje wyłącznie Empik.

Jakie są limity API Empik Place?

Po przekroczeniu limitu wywołań API zwraca błąd 429 z nagłówkiem Retry-After. Paginacja zwraca domyślnie 10, a maksymalnie 100 elementów na stronę, a pliki mogą mieć do 100 MB. Szczegółowe limity są opisane w dokumentacji.

Czy jest środowisko testowe dla API Empiku?

Tak, Empik udostępnia bezpłatne środowisko testowe do nauki panelu, dodawania testowych ofert i produktów. Testowe zamówienia składają pracownicy Empiku na prośbę zgłoszoną do supportu.

Czy muszę budować własną integrację, żeby korzystać z API?

Nie. Gotowe wtyczki sklepów i systemy wielokanałowe korzystają z API Empiku za Ciebie. Własna integracja ma sens głównie przy niestandardowych procesach, własnym ERP lub dużej skali.

Podsumowanie

API Empik Place pozwala zautomatyzować praktycznie cały cykl sprzedaży: oferty, karty produktów, zamówienia, dokumenty i wiadomości. Kluczem do stabilnej integracji jest przestrzeganie zasad technicznych – JSON, kompatybilność wsteczna, obsługa limitów – oraz monitoring raportów błędów i wskaźników jakości. Dla większości sprzedawców najlepszym wyborem będzie gotowa integracja, a własne API warto budować przy niestandardowych procesach. Zasady pracy z interfejsem opisuje Developer Portal Empik Place.

Planujesz integrację z API Empiku albo chcesz sprawdzić, czy gotowe narzędzie wystarczy? Jako certyfikowany partner Empik Place pomagamy zaprojektować i wdrożyć integrację oraz uporządkować dane – sprawdź naszą obsługę sprzedaży na Empiku.