Jak połączyć magazyn z Amazon, Kaufland i Empik: pobieranie zamówień oraz zgłaszanie wysyłek i stanów ofert przez API, z różnicami między platformami.
Marketplace przyjmuje zamówienia, ale towar leży w magazynie sprzedawcy. Magazyn musi więc zgłosić platformie, że paczka wyszła, jakim przewoźnikiem, pod jakim numerem i ile sztuk zostało w ofercie.
Ta strona opisuje trzy platformy i różnice między ich API. Zamówienia z Allegro opisuje osobna strona o integracji WMS z Allegro, a zamówienia ze sklepu i z agregatora integracja WMS z BaseLinkerem. Ogólny przepływ danych z platformami opisuje integracja WMS z platformami e-commerce, a pracę magazynu sklepu strona o WMS dla e-commerce. Dokumentacja platform jest podlinkowana w sekcjach (stan na 6.10.2026), a zakres po stronie Studio WMS.net ustala analiza przedwdrożeniowa.
Wspólny wzorzec wymiany z marketplace
Te same pięć wymian, inne nazwy endpointów.
Różnią się nazwy wywołań i statusy, a nie kolejność. Zlecenie wydania i dokument WZ powstają tak samo jak przy sprzedaży ze sklepu.
| Wymiana | Kierunek | Co przenosi | Czego pilnować |
|---|---|---|---|
| Zamówienia | Platforma do WMS | Pozycje, adres, metoda dostawy, płatność | Pobierać po czasie ostatniej zmiany i zakładać zlecenie dopiero po opłaceniu |
| Potwierdzenie wysyłki | WMS do platformy | Przewoźnik, numer przesyłki, data nadania | Numer musi dotrzeć razem ze statusem albo przed nim |
| Stany | WMS do platformy | Stan dostępny po rezerwacjach | Wysyłać wartość bezwzględną, nie przyrost |
| Anulowania | Platforma do WMS | Zwolnienie rezerwacji | Sprawdzić status zamówienia przed kompletacją |
| Zwroty | Platforma do WMS | Zgłoszenie, przyjęcie paczki, decyzja | Zwrot pieniędzy zostaje po stronie sprzedawcy i platformy |
Różnice między platformami
Ten sam cykl, trzy różne zestawy wywołań.
Tabela zestawia to, co potwierdza oficjalna dokumentacja, a odnośniki do niej stoją w opisach platform poniżej. Amazon opisuje też stronę Orders API v0.
| Cecha | Amazon SP-API | Kaufland Seller API | Empik (Mirakl) |
|---|---|---|---|
| Uwierzytelnianie | Token LWA ważny godzinę, odnawiany tokenem odświeżania | Podpis HMAC SHA256 w nagłówkach Shop-* | Klucz w nagłówku Authorization; Empik opisuje też token OAuth2 |
| Lista zamówień | GET /orders/v0/orders z LastUpdatedAfter albo CreatedAfter | GET /orders oraz GET /order-units, paginacja offset i limit | GET /api/orders (OR11) z start_update_date; eksport asynchroniczny OR13 |
| Zwolnienie zamówienia | Status Unshipped po autoryzacji płatności | Adres dostępny 15 minut plus 1 po zakupie | OR21 akceptuje lub odrzuca linie w stanie WAITING_ACCEPTANCE |
| Potwierdzenie wysyłki | POST /orders/v0/orders/{orderId}/shipmentConfirmation | PATCH /order-units/{id}/send z carrier_code i tracking_numbers | OR23 (tracking), potem OR24 (ship) w stanie SHIPPING |
| Zmiana stanu oferty | PATCH Listings Items, atrybut fulfillment_availability | PATCH /units/{id_unit}, pole amount; hurtowo POST /units/bulk | OF24 (POST /api/offers): wszystkie pola oferty naraz |
| Powiadomienia | Notifications API do kolejki SQS lub EventBridge | Push na publiczny adres callback | Zalecane odpytywanie OR11 w stałych odstępach |
| Limity | Odczyt zamówień: 1 żądanie na minutę, seria do 20 | 111 żądań na sekundę na sprzedawcę, potem kod 429 | Zalecana częstotliwość podana przy każdej operacji |
Amazon SP-API: zamówienia i stany
Limity i zapowiedziana zmiana wersji decydują o sposobie pobierania.
Amazon udostępnia zamówienia przez Orders API v0. Operacja getOrders zwraca zamówienia utworzone lub zmienione w podanym okresie, a parametr LastUpdatedAfter obejmuje każdą zmianę statusu, także tę wykonaną przez sprzedawcę. Zlecenie wydania ma sens od statusu Unshipped, bo w Pending płatność nie jest autoryzowana, a getOrderItems nie zwraca cen ani podatków.
Wysyłkę potwierdza operacja confirmShipment. Wymaga kodu przewoźnika, numeru przesyłki, daty nadania i pozycji z ilościami, a przy kodzie Other także nazwy przewoźnika. Odczyt listy zamówień ma domyślny limit jednego żądania na minutę, więc pobieranie musi być przyrostowe i korzystać z NextToken. Limity opisuje dokumentacja planów użycia, a dostęp opiera się na tokenach Login with Amazon ważnych godzinę.
Amazon zapowiada zmianę: Orders API v2026-01-01 zastępuje sześć operacji odczytu dwiema: getOrder oraz searchOrders. Znosi też Restricted Data Token przy danych osobowych. Wersję v0 trzeba porzucić do 27.03.2027, co opisuje przewodnik migracji. Stan oferty wysyłanej z własnego magazynu zmienia patchListingsItem z atrybutem fulfillment_availability i ilością (przewodnik po listingach). Koniec przetwarzania plików Feeds API sygnalizuje powiadomienie FEED_PROCESSING_FINISHED (lista powiadomień).
Kaufland: zamówienia i etykiety
Bez potwierdzenia wysyłki platforma nie wypłaca środków.
Kaufland pokazuje zamówienie jako listę jednostek (order units). Dokumentacja podaje, że adres kupującego jest dostępny dopiero 15 minut plus 1 po zakupie, więc zlecenie wydania nie powstanie wcześniej. Wysyłkę zgłasza PATCH /order-units/{id}/send z kodem przewoźnika i numerami przesyłek, a numer jest wymagany poza kodami Other i Other Hauler. Według zasad zarządzania zamówieniami bez potwierdzenia wysyłki środki ze sprzedaży nie zostaną wypłacone.
Stan zmienia PATCH /units/{id_unit}: pole amount przyjmuje do 99 999 sztuk, a endpointy jednostek obsługują też czas przygotowania i magazyn. Limit to 111 żądań na sekundę na sprzedawcę (limity). Powiadomienia push trafiają na publiczny adres callback, który musi odpowiedzieć w pięć sekund, więc usługa działająca tylko z ruchem wychodzącym odpytuje API zamiast je odbierać.
Etykiety wydaje moduł Kaufland Shipment Solutions (POST /shipping-labels). Dokumentacja podaje obecnie jednego przewoźnika, GLS, i zastrzega, że utworzenie etykiety nie oznacza zamówienia jako wysłanego. Zwroty obsługuje GET /returns, a decyzje PATCH /return-units/{id}/accept lub reject (dokumentacja zwrotów).
Empik i Mirakl: zamówienia i oferty
Empik pracuje na platformie Mirakl, a jego instancja ma własne ustawienia.
Empik opisuje integrację sprzedawcy przez Mirakl Connect z tokenem OAuth2 ważnym godzinę (pomoc EmpikPlace). Klasyczne API sprzedawcy Mirakl używa klucza w nagłówku Authorization, a który wariant obowiązuje w danej instalacji, potwierdza dokumentacja Empik i analiza przedwdrożeniowa. Zamówienia pobiera OR11 z filtrem start_update_date, a przy dużych wolumenach Mirakl zaleca eksport asynchroniczny OR13.
Linie w stanie WAITING_ACCEPTANCE akceptuje lub odrzuca OR21. Wysyłkę zgłaszają dwa wywołania: OR23 zapisuje przewoźnika i numer, a OR24 zatwierdza wysyłkę zamówienia w stanie SHIPPING i wymaga nagłówka Content-Length równego 0. Zwroty pieniędzy wykonuje OR28.
Pułapka dotyczy ofert: OF24 wymaga wysłania wszystkich pól oferty, bo pola pominięte wracają do wartości domyślnych. Aktualizacja samej ilości zresetowałaby więc pozostałe dane oferty.
Stan oferty wysyłaj jako wartość bezwzględną z magazynu. Na Mirakl dodaj do niej pełny zestaw pól oferty, bo pominięte pole zostanie zresetowane.
Fulfilment zewnętrzny a własny magazyn
Od tego, kto wysyła paczkę, zależy, czy WMS prowadzi zapas.
Gdy wysyła platforma, towar leży poza magazynem, więc program prowadzi go jako osobną lokalizację, jak przy magazynie Allegro opisanym na stronie o integracji z Allegro. Stany takiego zapasu opisuje strona o stanach magazynowych.
| Wariant | Kto wysyła | Co widzi WMS | Źródło w dokumentacji |
|---|---|---|---|
| Własny magazyn | Sprzedawca | Pełny obieg: zlecenie, WZ, numer przesyłki | Wszystkie trzy platformy |
| Amazon, wysyłka przez Amazon (AFN) | Amazon | Zapas jako lokalizacja zewnętrzna; zmiany w powiadomieniu FBA_INVENTORY_AVAILABILITY_CHANGES | Lista powiadomień |
| Amazon, Multi-Channel Fulfillment | Amazon, na zlecenie z innego kanału | Fulfillment Outbound API pozwala utworzyć zamówienie i pobrać śledzenie | Fulfillment Outbound API |
| Kaufland | Sprzedawca | Fulfillment by Kaufland zakończono 28.02.2025; zostaje wysyłka własna | Informacja o zakończeniu usługi |
| Empik (Mirakl) | Sprzedawca | Dokumentacja opisuje wysyłkę przez sprzedawcę; inne warianty ustala analiza | OR24 |
Błędy i ponowienia
Integracja ma wrócić do poprawnego stanu bez ręcznej pracy.
Wspólna zasada dla trzech platform brzmi: żaden komunikat nie ginie i żaden nie wykonuje się dwa razy. Limity i tokeny są zjawiskiem normalnym, a nie awarią, więc obsługuje je kolejka z ponawianiem.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Przekroczony limit, kod 429 | Odrzucone wywołanie | Kolejka z ponawianiem i rosnącym odstępem, bez utraty komunikatu |
| Wygasły token | Wszystkie zapytania odrzucone | Odnowienie tokenu i alarm po nieudanej próbie |
| Zamówienie jeszcze nieopłacone | Amazon: Pending; Kaufland: brak adresu przez 15 minut plus 1 | Czekanie na stan zwalniający, bez rezerwacji towaru |
| Numer przesyłki bez zatwierdzenia | Mirakl: zamówienie zostaje w SHIPPING; Kaufland: brak wypłaty | Kontrola odpowiedzi i drugie wywołanie po zapisie numeru |
| Aktualizacja oferty z brakującymi polami | Mirakl: pola wracają do wartości domyślnych | Wysyłka pełnego zestawu pól oferty |
| To samo zamówienie pobrane dwa razy | Zdwojone zlecenie wydania | Odrzucenie po zewnętrznym numerze zamówienia i unikalny identyfikator komunikatu |
Kto wykonuje integracje po stronie Studio WMS.net
Usługa Windows na serwerze, a zakres dla platformy potwierdza analiza.
Integracje w Studio WMS.net wykonuje usługa Windows SSService.exe, instalowana na serwerze klienta. Łączy się z platformami wyłącznie ruchem wychodzącym HTTPS, bez publikowania punktu dostępowego w Internecie. Komunikaty trafiają do tabeli wysyłkowej (outbox) z ponawianiem i unikalnym identyfikatorem, więc wznowienie łączności nie tworzy duplikatów. Pełny log wymiany zostaje w bazie.
Cennik Studio WMS.net zawiera moduł integracji (API, import z plików, serwer FTPS). Ta strona nie deklaruje gotowych konektorów do tych platform. Opisuje drogi wymiany, a zakres potwierdza analiza przedwdrożeniowa. Numer listu rejestruje się tak, jak opisuje strona o firmach kurierskich, a paczkę przygotowuje pakowanie i kontrola wysyłki.
Co ustala analiza przedwdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Zakres integracji z marketplace wynika z analizy przedwdrożeniowej. Lista decyzji ma cztery pozycje:
- Platformy i konta - które sklepy krajowe, ile kont i czy zamówienia idą bezpośrednio, czy przez warstwę pośrednią.
- Kanał realizacji - wysyłka własna czy fulfilment platformy, a przy fulfilmencie sposób prowadzenia zapasu zewnętrznego.
- Reguły stanów - podział jednej puli między kanały i zapas bezpieczeństwa.
- Zwroty - kto przyjmuje paczkę, kto ocenia towar i kto zleca zwrot pieniędzy.
Zwroty trafiają do magazynu jak każde przyjęcie.