Magento i Allegro: jak uniknąć nadsprzedaży towaru?

Nadsprzedaż (overselling) na Allegro wynika z asynchroniczności: zamówienie złożone na marketplace blokuje towar z opóźnieniem, podczas gdy ten sam produkt schodzi w sklepie na Magento lub w stacjonarnym ERP. Aby wyeliminować ten problem, musisz wdrożyć natychmiastowe rezerwacje w Magento Multi-Source Inventory (MSI), uruchomić dedykowaną kolejkę RabbitMQ do wypychania zmian stanów przez Allegro REST API oraz ustawić tzw. bufor bezpieczeństwa na poziomie integratora. Prawidłowo zaprojektowana integracja Magento z Allegro traktuje stany w czasie rzeczywistym, nie opierając się na tradycyjnym cronie odpalanym co 15 minut.

Dlaczego standardowy cron w Magento nie wystarcza do kontroli stanów?

Klasyczny model integracji, w którym moduł pyta bazę co kwadrans o zmodyfikowane produkty (updated_at > NOW() - INTERVAL 15 MINUTE), w szczycie sprzedażowym — na przykład podczas Black Friday czy akcji Allegro Days — jest gwarancją katastrofy. Jeśli masz na stanie 2 sztuki unikalnego ekspresu do kawy, a klient na Magento wrzuci go do koszyka i opłaci przez BLIK lub Przelewy24 o 14:02, to do godziny 14:15 Allegro nadal wyświetla pełną dostępność. Drugi klient kupuje ten sam produkt przez Allegro Smart! o 14:05. Masz podwójną sprzedaż, jeden towar fizyczny i 24 godziny na wysyłkę, zanim wskaźnik Jakości Sprzedaży na Allegro poleci w dół.

Standardowe zapytania MySQL przy 30 000 SKU potrafią zablokować tabele (lock wait timeout), zwłaszcza gdy w tle Comarch ERP Optima lub Subiekt nexo właśnie wykonują pełną synchronizację cenników. U nas w projektach eliminujemy cykliczne odpytywanie całej bazy na rzecz architektury sterowanej zdarzeniami (Event-Driven Architecture). Zmiana w cataloginventory_stock_status lub rezerwacja w MSI natychmiast wrzuca payload z sku oraz qty do kolejki AMQP (RabbitMQ), skąd dedykowany consumer uderza bezpośrednio w endpoint Allegro: PUT /sale/offer-quantity-change-commands/{commandId}.

Gdzie powinien znajdować się Master of Stock: ERP, Magento czy BaseLinker?

Najczęstszy błąd architektoniczny w polskich e-commerce to brak jasnego wskazania jednego źródła prawdy (Single Source of Truth). Powstaje wtedy pętla: Subiekt GT wysyła stan 5 sztuk do Magento, Magento wypycha to do BaseLinkera, w międzyczasie na Allegro wpada zamówienie, BaseLinker zmniejsza stan u siebie, a za 3 minuty cron z Optimy nadpisuje wszystko stanem 5, bo magazynier jeszcze nie zatwierdził dokumentu WZ.

Układ musi być hierarchiczny i jednoznaczny:

• Wariant A (ERP jako Master): Magazyn wysokiego składowania (WMS/ERP) zarządza fizycznym towarem. Magento przyjmuje zamówienia, zakłada rezerwacje w MSI i wysyła do ERP dokument ZK (Zamówienie od Klienta). ERP rozgłasza skorygowany stan do Magento, a Magento asynchronicznie aktualizuje oferty na Allegro.
• Wariant B (Magento jako Master): Stosowany przy braku zaawansowanego WMS. Magento 2.4.7 zarządza źródłami (Sources) i zasobami (Stocks). Każde zamówienie z Allegro pobrane przez API tworzy zamówienie w Magento, natychmiast konsumując rezerwację. ERP dostaje gotowy rekord przez szynę danych po przejściu płatności.

Jeśli BaseLinker pośredniczy w wystawianiu ofert, wyłącz w nim automatyczną synchronizację co godzinę, jeśli masz spięty webhook z Magento. Dwa systemy próbujące w tym samym czasie ustalać stan magazynowy zawsze doprowadzą do błędu 409 Conflict lub nadsprzedaży.

Jak skonfigurować Magento Multi-Source Inventory (MSI), aby zabezpieczyć stany?

Magento 2 od wersji 2.3 w górę domyślnie korzysta z MSI. Wiele wdrożeń ma z tym problem, bo deweloperzy zamiast zrozumieć mechanizm rezerwacji, instalują moduły czyszczące tabelę inventory_reservation bezpośrednim zapytaniem SQL. To prosty sposób na rozjechanie stanów z Allegro.

Gdy klient na Allegro kupuje produkt, Twoja integracja musi utworzyć w Magento tzw. Order Placement, co generuje ujemny wpis w inventory_reservation (np. -1.0000 dla danego SKU i Stock ID), ale nie zmienia od razu wartości w cataloginventory_stock_item.qty. Rzeczywisty stan fizyczny zmniejsza się dopiero w momencie wystawienia dokumentu Shipment.

Aby Allegro widziało właściwy stan (Quantity minus Reservations), endpoint integracyjny musi odpytywać interfejs GetSalableQuantityInterface, a nie pobierać surowe qty z tabeli produktowej:

// Prawidłowe pobranie ilości możliwej do sprzedaży w Magento 2.4.7
use Magento\InventorySalesApi\Api\GetSalableQuantityInterface;

$salableQty = $this->getSalableQuantity->execute($sku, $stockId);

Jeśli pominiesz ten interfejs, Allegro dostanie stan nieuwzględniający zamówień oczekujących na płatność lub weryfikację w panelu sklepu.

Jakie ograniczenia techniczne nakłada Allegro REST API?

Allegro zabezpiecza swoją infrastrukturę restrykcyjnymi limitami Rate Limitingu. Próba zaktualizowania 10 000 ofert jednocześnie po porannej dostawie w hurtowni skończy się kodem odpowiedzi HTTP 429 Too Many Requests i czasowym zablokowaniem tokenu OAuth aplikacji.

Do bezpiecznej komunikacji z API Allegro należy stosować:

1. Batch updates: Zamiast pojedynczych zapytań dla każdej oferty, wykorzystaj komendy masowe. Allegro pozwala na aktualizację do kilkudziesięciu ofert w jednym żądaniu.
2. Kolejkowanie z Backoff Strategy: W SISL konfigurujemy consumery CLI w oparciu o Symfony Messenger lub natywne kolejki Magento. Jeśli Allegro zwróci 429 lub błąd 503 Service Unavailable, payload wraca na koniec kolejki z opóźnieniem wykładniczym (exponential backoff: 2s, 4s, 8s, 16s).
3. UUID per żądanie: Wykorzystuj nagłówek idempotencji, aby powtórzone zapytanie nie zmieniło stanu dwukrotnie przy zerwanym połączeniu TCP.

Bufor bezpieczeństwa: jak zdefiniować Virtual Safety Stock?

W praktyce handlowej 100% zaufanie do systemów IT bywa ryzykowne — towar może ulec uszkodzeniu na magazynie, klient stacjonarny może zbić butelkę na półce, a magazynier może pomylić kody EAN. Dlatego niezbędny jest bufor bezpieczeństwa (Safety Stock Buffer).

Zasada jest prosta: wystawiasz na Allegro ilość obliczaną według reguły:

Stan_Allegro = MAX(0, Salable_Quantity - Bufor)

Dla towarów o wysokiej rotacji i niskiej marży bufor powinien wynosić 1–2 sztuki. Gdy w Magento zostają 2 sztuki, integracja wysyła do Allegro qty: 0 lub wywołuje akcję zakończenia oferty: PUT /sale/offer-publication-commands/{commandId} z flagą END. Towar wciąż można kupić bezpośrednio w Twoim sklepie internetowym, ale Allegro nie wygeneruje nadsprzedaży w nocy, gdy nikt nie kontroluje magazynu.

Co zrobić z fakturami i KSeF w razie wystąpienia błędu?

Jeśli dojdzie do nadsprzedaży, konsekwencje nie kończą się na anulowaniu zamówienia w panelu Allegro. W polskim systemie prawno-podatkowym generuje to szereg problemów formalnych:

• Krajowy System e-Faktur (KSeF): Jeśli system automatycznie wystawił fakturę bez upewnienia się o fizycznej dostępności towaru i przesłał ją do KSeF z nadanym numerem identyfikacyjnym, nie można jej po prostu usunąć. Wymagane jest wystawienie faktury korygującej do zera z odpowiednią przyczyną korekty i ponowne przesłanie do KSeF.
• Biała lista podatników VAT i zwroty: Zwrot środków za nadsprzedany towar opłacony przelewem tradycyjnym powyżej 15 000 PLN brutto (transakcje B2B na Allegro Biznes) musi trafić na rachunek zgłoszony na białej liście, co wymaga ręcznej weryfikacji w wykazie MF.
• Dyskusje na Allegro: Brak towaru oznacza konieczność natychmiastowego zwrotu środków przez API PayU/P24 w Allegro, aby kupujący nie otworzył Dyskusji. Każda nierozwiązana w ciągu 24h dyskusja drastycznie obniża pozycję wszystkich Twoich ofert w algorytmie trafności.

Ile kosztuje eliminacja nadsprzedaży w Magento 2?

Koszt wdrożenia stabilnej architektury synchronizacji zależy od skali bazy produktowej i używanego oprogramowania ERP:

• Dedykowany moduł asynchroniczny (PHP 8.3, RabbitMQ, wsparcie MSI): Od 8 000 do 18 000 PLN netto przy wdrożeniu bespoke, uwzględniającym specyficzne logiki magazynowe (np. warianty, zestawy bundled products, fractional quantities).
• Modyfikacja architektury middleware (np. n8n, Apache Camel, dedykowana szyna w Go/Node): Od 12 000 do 25 000 PLN netto przy obsłudze powyżej 100 000 SKU i wielu kont Allegro.
• Audyt wydajnościowy kolejkowania i naprawa bazy MSI: Od 3 500 do 6 000 PLN netto. Często wystarczy naprawa błędnych rezerwacji (bin/magento inventory:reservation:list-inconsistencies) oraz optymalizacja indeksów MySQL.

Jeśli masz problem z rozjeżdżającymi się stanami na Allegro, a Twój obecny software house powtarza, że „tak działa API Allegro i nic się nie da zrobić” — napisz do nas. Przeanalizujemy strukturę Twojej bazy, sprawdzimy crony i wdrożymy architekturę, która uniemożliwia sprzedaż towaru, którego nie masz na półce.