Jak połączyć magazyn z Allegro: zdarzenia zamówień, numer przesyłki przed statusem wysłane i stan oferty, przez BaseLinker albo bezpośrednio przez API Allegro.
Na Allegro kupujący widzi termin wysyłki i numer przesyłki, więc magazyn odpowiada nie tylko za spakowanie towaru, ale też za to, co o nim zgłosi do platformy. Pomyłka w statusie jest od razu widoczna po stronie kupującego.
Zamówienia z Allegro mogą trafić do magazynu przez BaseLinker, któremu poświęcona jest strona o integracji WMS z BaseLinkerem, albo bezpośrednio z API Allegro. Ogólny przepływ danych z platformami opisuje integracja WMS z platformami e-commerce, a pracę magazynu sklepu strona o WMS dla e-commerce. Ta strona opisuje mechanizmy Allegro, z którymi każda droga musi się zgadzać. Zakres po stronie Studio WMS.net ustala analiza przedwdrożeniowa. Dane o API pochodzą z dokumentacji dla deweloperów Allegro (stan na 6.10.2026).
Trzy drogi do zamówień z Allegro
Warstwa pośrednia, własne API albo magazyn Allegro.
Wybór drogi zależy od liczby kanałów sprzedaży i od tego, kto fizycznie wysyła towar. Każda droga inaczej rozkłada odpowiedzialność za stany i statusy.
| Droga | Jak działa | Kiedy pasuje | Konsekwencja |
|---|---|---|---|
| Przez BaseLinker | Allegro jest jednym ze źródeł zamówień, a magazyn rozmawia tylko z BaseLinkerem | Sprzedaż na kilku kanałach naraz | Limity i dostępność warstwy pośredniej wpływają na magazyn |
| Bezpośrednio przez API Allegro | Integracja czyta zdarzenia zamówień i odsyła statusy, numery przesyłek oraz stany | Sprzedaż głównie na Allegro | Własna obsługa autoryzacji OAuth 2.0 i limitów |
| Magazyn Allegro (One Fulfillment) | Towar leży w magazynie Allegro, a sprzedawca dostaje dane o stanie i paczkach | Logistykę przejmuje Allegro | WMS prowadzi ten zapas jako lokalizację zewnętrzną |
Przepływ zamówienia z Allegro
Zlecenie wydania powstaje po jednym konkretnym zdarzeniu.
Allegro udostępnia strumień zdarzeń zamówień (GET /order/events) i dane pojedynczego zamówienia (GET /order/checkout-forms/{id}). Zdarzenie BOUGHT oznacza zakup bez płatności. FILLED_IN pojawia się po wypełnieniu formularza dostawy i może wystąpić kilka razy, gdy kupujący go zmienia. READY_FOR_PROCESSING przychodzi po zakończeniu płatności i potwierdzeniu adresu. Zleceniem wydania powinno stać się dopiero to ostatnie, a dla płatności przy odbiorze moment zwolnienia ustala analiza.
Dokumentacja ostrzega, że zdarzenia mogą dotrzeć w nieoczekiwanej kolejności, a dostępne są z ostatnich 60 dni. Integracja zapisuje więc numer ostatniego przetworzonego zdarzenia i decyduje na podstawie bieżących danych zamówienia, a nie samej kolejności. O nowych zdarzeniach informuje GET /order/event-stats, które zwraca najnowsze z nich.
Stany i źródło prawdy
Ta sama sztuka nie może być policzona w dwóch miejscach.
Oferta Allegro ma własną liczbę sztuk, a WMS własny stan dostępny. Zakup zmniejsza liczbę w ofercie od razu, natomiast rezerwacja w WMS powstaje dopiero po przetworzeniu zdarzenia. Przez krótki czas ta sama sztuka bywa więc policzona dwa razy i integracja nie może jej odjąć po raz drugi.
Liczbę sztuk w ofertach zmienia się przez API. Zmiana seryjna jest poleceniem wykonywanym asynchronicznie i ma raport z wynikiem dla każdej oferty, więc przed ponowieniem trzeba ten raport odczytać. Bezpieczniej wysyłać wartość bezwzględną, czyli pełny stan dostępny, niż przyrost: powtórzona wartość niczego nie psuje, a powtórzony przyrost zniekształca stan.
| Sytuacja | Co widzi Allegro | Co robi integracja |
|---|---|---|
| Zakup przed utworzeniem zlecenia | Liczba w ofercie już zmniejszona | Nie odejmuje sztuki drugi raz, a stan dostępny liczy po rezerwacji |
| Anulowanie przez kupującego | Zdarzenie BUYER_CANCELLED | Zwalnia rezerwację i koryguje liczbę w ofercie |
| Korekta po inwentaryzacji | Oferta z dotychczasową liczbą | Wysyła nową wartość bezwzględną |
| Kilka kont Allegro, jeden zapas | Osobne oferty na każdym koncie | Dzieli pulę według reguły z analizy |
Statusy realizacji i numery przesyłek
Numer listu przewozowego jest częścią zgłoszenia wysyłki, nie dodatkiem.
Status realizacji ustawia się wywołaniem PUT /order/checkout-forms/{id}/fulfillment z jednym polem status. Dokumentacja podaje dziewięć wartości, wśród nich PROCESSING i SENT. Opcjonalny parametr checkoutForm.revision chroni przed nadpisaniem cudzej zmiany: gdy zamówienie zmieniło się w międzyczasie, Allegro odpowiada kodem 409 CONFLICT.
Numer przesyłki dodaje się osobnym wywołaniem POST /order/checkout-forms/{id}/shipments z identyfikatorem przewoźnika (lista z GET /order/carriers) i numerem listu przewozowego. Dopiero potem ustawia się status SENT. Tabela proponuje odpowiedniki dla etapów w magazynie.
| Etap w WMS | Dokument | Status w Allegro |
|---|---|---|
| Zlecenie wydania zapisane, towar zarezerwowany | ZWZ | PROCESSING |
| Kompletacja i pakowanie zakończone | WZ w toku | READY_FOR_SHIPMENT |
| Paczka przekazana kurierowi, numer zapisany | WZ zamknięty | SENT po dodaniu numeru listu |
| Odbiór osobisty | WZ zamknięty | READY_FOR_PICKUP, potem PICKED_UP |
Numer przesyłki trafia do Allegro przed statusem wysłane. Odwrotna kolejność daje zamówienie oznaczone jako wysłane, którego kupujący nie może śledzić.
Etykiety kurierskie
Etykieta powstaje po pakowaniu, a jej źródło zależy od umowy z przewoźnikiem.
Allegro obsługuje przesyłki także samo, pod nazwą Wysyłam z Allegro: API zakłada przesyłkę (POST /shipment-management/shipments) i zwraca etykiety oraz protokoły. Wtedy etykieta powstaje po stronie Allegro, a magazyn ją drukuje. Przy własnej umowie z przewoźnikiem etykietę przygotowuje system kuriera albo Studio Spedycja.net, które rejestruje numer listu i kojarzy go z dokumentem WZ, jak opisuje strona o wysyłce przez firmy kurierskie. Do Allegro wraca wtedy sam numer.
Po przekazaniu numeru Allegro udostępnia historię przesyłki (GET /order/carriers/{carrierId}/tracking) ze statusami od PENDING do DELIVERED, a także RETURNED, do 20 numerów w zapytaniu. Magazyn korzysta z niej do wychwytywania paczek wracających. Oferty z oznaczeniem Allegro Smart! muszą mieć metody dostawy wskazane w warunkach programu, więc lista przewoźników na stanowisku pakowania wynika częściowo z tych warunków.
Zwroty od kupujących
Magazyn odpowiada za część fizyczną, a pieniądze zostają po stronie sprzedawcy.
Zwroty zgłoszone przez kupujących udostępnia GET /order/customer-returns, a szczegóły pojedynczego zwrotu GET /order/customer-returns/{id}. Odrzucenie zwrotu przechodzi przez POST /order/customer-returns/{id}/rejection, a zwrot pieniędzy przez POST /payments/refunds. Magazyn przyjmuje paczkę dokumentem przyjęcia, ocenia towar i zapisuje wynik. Decyzję o wypłacie podejmuje sprzedawca, najczęściej w systemie finansowym, więc WMS nie wywołuje zwrotu płatności sam.
Towar nienaruszony wraca na półkę sprzedażową, a uszkodzony trafia na osobną lokalizację. Szerzej opisuje to sekcja o zwrotach na stronie o WMS dla e-commerce.
Magazyn Allegro jako lokalizacja zewnętrzna
W modelu One Fulfillment sprzedawca widzi dane, ale nie wysyła paczek.
W usłudze One Fulfillment by Allegro towar leży w magazynie Allegro, a ten magazyn go przechowuje i wysyła zamówienia. Dostawy zapowiada się awizami (POST /fulfillment/advance-ship-notices), które przechodzą statusy od DRAFT do COMPLETED, a stan odczytuje GET /fulfillment/stock. Dla WMS to osobna lokalizacja: towar wysłany do Allegro znika ze stanu dostępnego dla wysyłek z własnego magazynu. Czy i jak program ma prowadzić taki zapas, ustala analiza przedwdrożeniowa.
Błędy i ponowienia
Integracja ma wrócić do poprawnego stanu bez ręcznej pracy.
Allegro uwierzytelnia wywołania protokołem OAuth 2.0, a token dostępu ma ograniczoną ważność. Integracja odnawia go sama i zgłasza alarm, gdy odnowienie się nie uda. Operacje seryjne zwracają kod 202 i wykonują się w tle. Lista zamówień ma limit: suma parametrów offset i limit nie przekracza 10 000, więc do ciągłego pobierania służy strumień zdarzeń.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Zdarzenia w innej kolejności | Zlecenie przed potwierdzeniem płatności | Decyzja według bieżących danych zamówienia |
| 409 CONFLICT przy zmianie statusu | Zamówienie zmieniło się w międzyczasie | Pobranie zamówienia, ponowna ocena i ponowienie z nową rewizją |
| Wygasły token dostępu | Wszystkie zapytania odrzucone | Odnowienie tokenu, alarm po nieudanej próbie |
| Polecenie seryjne zwróciło 202 | Wynik nieznany do odczytu raportu | Odczyt raportu przed ponowieniem |
| Ten sam identyfikator zamówienia dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
Kto wykonuje integracje po stronie Studio WMS.net
Usługa Windows na serwerze, a zakres dla Allegro potwierdza analiza.
Integracje w Studio WMS.net, w tym z platformami sprzedażowymi, wykonuje usługa Windows SSService.exe. Instaluje się ją na serwerze. Usługa realizuje zadania, a wymiana danych z innym systemem jest jednym z nich.
Z Allegro wymiana idzie przez API serwisu, na przykład przez strumień zdarzeń GET /order/events i dane zamówienia GET /order/checkout-forms/{id}. Zamówienia mogą też dotrzeć przez BaseLinker, któremu poświęcona jest integracja WMS z BaseLinkerem. Zakres dla danej platformy potwierdza analiza przedwdrożeniowa, a ta strona opisuje drogi wymiany, nie listę gotowych funkcji.
Co ustala analiza wdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Zakres integracji z Allegro wynika z analizy przedwdrożeniowej. Na liście decyzji są cztery pozycje:
- Droga integracji - przez BaseLinker czy bezpośrednio, a przy kilku kontach Allegro jedna wspólna warstwa dla wszystkich.
- Moment zwolnienia zamówienia - po zdarzeniu READY_FOR_PROCESSING, także dla płatności przy odbiorze, i obsługa zamówień zmienianych przez kupującego.
- Podział zapasu - jak dzielić jedną pulę między oferty Allegro i inne kanały oraz jaki zapas bezpieczeństwa zostaje.
- Przewoźnicy - Wysyłam z Allegro czy własne umowy oraz metody dostawy, których wymaga program Smart!.
Zakres prac programistycznych zależy od liczby i złożoności systemów, z którymi magazyn ma się komunikować, a zasady wyceny opisuje cennik.