Jak zaprojektować marketplace w MedusaJS, w którym każdy sprzedawca prowadzi własny katalog i zamówienia?

Źródła sprawdzone 10 listopada 2026, na dokumentacji Medusy v2; najnowsze wydanie w tym dniu to v2.22.6.

Ten poradnik jest dla CTO, product ownera albo operatora platformy, który chce, żeby wielu sprzedawców prowadziło w jednym sklepie osobne katalogi i samodzielnie obsługiwało swoje zamówienia. Opisuje, co trzeba zaprojektować po stronie modelu danych, uprawnień i procesów, zanim powstanie pierwszy ekran panelu sprzedawcy.

Odpowiedź w skrócie: rdzeń Medusy daje produkty, koszyki, zamówienia, uwierzytelnianie i mechanizmy rozszerzeń, ale nie daje sprzedawcy. Sprzedawcę, jego użytkowników, przypisanie produktów i podział zamówień buduje się jako własny moduł. Największe ryzyko nie leży w kodzie modułu, tylko w izolacji danych: każdy endpoint sprzedawcy musi zwracać i zmieniać wyłącznie jego dane.

Przewodnik Medusy po marketplace mówi wprost, że funkcje marketplace powstają w module, który definiuje własne modele, na przykład sprzedawców. Opis: przepis Medusy na marketplace.

Przykład w dokumentacji tworzy moduł z dwoma modelami, Vendor i VendorAdmin, i łączy sprzedawcę z produktami oraz zamówieniami przez powiązania modułów. Powiązanie to osobna tabela łącząca, podobna do tabeli pośredniej, więc rdzeniowe tabele produktów i zamówień pozostają nienaruszone. Opis: przykład modułu sprzedawców.

Poniższa tabela porządkuje, co pochodzi z rdzenia, a co jest Twoją decyzją projektową. To stan dokumentacji z 10 listopada 2026; przy innej wersji Medusy sprawdź go ponownie.

W przykładzie z dokumentacji sprzedawca ma nazwę, unikalny identyfikator w adresie i logo, a jego administratorzy mają imię, nazwisko i unikalny e-mail. To minimum techniczne. Model biznesowy prawie zawsze potrzebuje więcej i warto to ustalić przed pierwszą migracją.

Najczęstszy błąd to utożsamienie sprzedawcy z jednym kontem użytkownika. Firma sprzedająca ma zwykle kilka osób: właściciela, osobę od katalogu, magazyn i księgowość. Jeśli od początku sprzedawca i jego użytkownicy są osobnymi bytami, dodanie ról nie wymaga późniejszej przebudowy.

1. Statusy sprzedawcy: zgłoszony, w weryfikacji, aktywny, zawieszony, zamknięty. Każdy status mówi, czy oferty są widoczne i czy można złożyć zamówienie.
2. Role w obrębie sprzedawcy: kto może publikować oferty, kto realizuje zamówienia, kto widzi rozliczenia.
3. Dane firmy i dokumenty: co weryfikuje operator przed aktywacją i kto może je zmienić po aktywacji.
4. Zaproszenia i odejścia: jak dodać nowego użytkownika sprzedawcy i jak odebrać dostęp osobie, która odchodzi.
5. Zawieszenie: co dzieje się z aktywnymi ofertami i otwartymi zamówieniami, gdy operator zawiesi sprzedawcę.

Moduł uwierzytelniania Medusy rozróżnia typy aktorów: wbudowany użytkownik panelu i klient sklepu, a także typy własne. W przykładzie dokumentacji administrator sprzedawcy loguje się jako aktor typu vendor, a identyfikator jego konta trafia do metadanych tożsamości. Opis: typy aktorów w module uwierzytelniania.

Trasy sprzedawcy chroni middleware authenticate z typem aktora vendor. To odpowiada na pytanie, kto jest zalogowany. Nie odpowiada na pytanie, do którego sprzedawcy należy produkt o podanym identyfikatorze. Tę drugą kontrolę musisz napisać sam w każdym endpoincie i w każdym workflow, który odczytuje albo zmienia dane. Opis: ochrona tras API.

Praktyczna reguła: identyfikator sprzedawcy zawsze wynika z kontekstu zalogowanego aktora, nigdy z parametru żądania. Jeśli endpoint przyjmuje identyfikator produktu albo zamówienia, najpierw sprawdza powiązanie tego rekordu ze sprzedawcą aktora, a dopiero potem cokolwiek zwraca.

Według opisu przykładu panel Medusa Admin jest przeznaczony dla operatora platformy, nie dla administratorów sprzedawców. Panel sprzedawcy to osobna aplikacja korzystająca z tras sprzedawcy, więc jej bezpieczeństwo zależy wyłącznie od tych tras.

• Test dwóch sprzedawców: każdy endpoint sprawdzaj kontem sprzedawcy A na danych sprzedawcy B. Oczekiwany wynik to brak dostępu, a nie pusta lista z poprawnym kodem.
• Listy i wyszukiwanie: filtr po sprzedawcy dotyczy też eksportów, raportów i podpowiedzi wyszukiwania.
• Zdarzenia i powiadomienia: e-mail o nowym zamówieniu idzie tylko do sprzedawcy, którego dotyczą pozycje.
• Logi operatora: działania operatora w imieniu sprzedawcy zapisuj z informacją, kto je wykonał.

W przykładzie dokumentacji produkt sprzedawcy powstaje w workflow, który tworzy produkt w module produktów, przypisuje go do domyślnego kanału sprzedaży i zapisuje powiązanie ze sprzedawcą. Workflow w Medusie to seria kroków, a krok może mieć funkcję kompensacji, która cofa jego zmiany, gdy workflow zakończy się błędem. Opis: workflows w Medusie.

Zadbaj o kompensację kroków, które zapisują dane. Przetestuj awarię powiązania po utworzeniu produktu i sprawdź, czy workflow usuwa produkt lub pozostawia go niedostępnego do czasu naprawy. Opis: funkcja kompensacji w Medusie.

Najważniejsza decyzja produktowa dotyczy tego, czy dwóch sprzedawców może oferować ten sam towar. Jeśli tak, potrzebujesz rozdzielenia wspólnej karty produktu od oferty sprzedawcy z jego ceną, stanem i czasem wysyłki. Jeśli nie, każdy sprzedawca ma własne produkty i duplikaty akceptujesz albo moderujesz.

Druga decyzja to moderacja. Operator może publikować oferty od razu albo po akceptacji. Akceptacja daje kontrolę jakości kosztem czasu sprzedawcy, więc często stosuje się ją tylko dla nowych sprzedawców lub wybranych kategorii.

Przepis Medusy opisuje odtworzenie trasy finalizacji koszyka i własny workflow, który dzieli zamówienie na osobne zamówienia, po jednym dla każdego sprzedawcy. Klient składa jedno zamówienie, a każdy sprzedawca widzi i realizuje tylko swoją część.

Z perspektywy sprzedawcy liczy się, co może zrobić ze swoim zamówieniem: potwierdzić, spakować, wysłać, częściowo anulować. Każdą z tych akcji projektuj tak, żeby zmieniała tylko część sprzedawcy, a stan całego zamówienia klienta wynikał ze stanów części.

Płatności, wypłaty dla sprzedawców, prowizje, faktury i zwroty to osobny, duży temat. Opisujemy go w poradniku o tym, jak podzielić koszyk, płatności i faktury w marketplace B2B, dlatego tutaj go nie powtarzamy.

Marketplace w Medusie warto budować tak, jak pokazuje dokumentacja: nowy moduł, powiązania, własne trasy i workflow, bez zmian w kodzie rdzenia. Wtedy aktualizacja Medusy dotyczy Twojego modułu tylko tam, gdzie zmieniają się interfejsy, z których korzysta.

Te interfejsy się zmieniają. Strony dokumentacji, do których odsyła ten poradnik, zawierają adnotacje o zmianach, na przykład od wersji v2.13.0 i v2.20.0. Dlatego zapisz wersję Medusy, na której projektujesz moduł, i przy każdej aktualizacji uruchom testy izolacji sprzedawców oraz podziału zamówień.

• Nie zmieniaj tabel rdzenia: własność produktu i zamówienia trzymaj w powiązaniach, nie w dodatkowych kolumnach rdzeniowych tabel.
• Nie forkuj rdzenia: każda poprawka w kodzie Medusy to koszt przy każdej aktualizacji.
• Przypnij wersję: zapisz wersję Medusy i wersję dokumentacji, na której opierasz decyzje.
• Testy przy aktualizacji: izolacja sprzedawców, publikacja oferty i podział zamówienia na środowisku testowym przed produkcją.

Strony dokumentacji Medusy sprawdzone 10 listopada 2026 nie wskazują gotowego modułu marketplace. Odsyłają do przykładowego kodu i przewodników. Istnieją projekty open source i rozwiązania firm trzecich budowane na Medusie, ale ich zakres, licencję i zgodność z Twoją wersją Medusy trzeba sprawdzić samodzielnie.

Gotowy moduł skraca start, jeśli jego model sprzedawcy, katalogu i zamówień pasuje do Twojego. Własny moduł jest rozsądniejszy, gdy marketplace jest głównym produktem firmy i różni się regułami, których gotowe rozwiązanie nie przewiduje. Poniższe pytania pomagają rozstrzygnąć to na faktach.

Te materiały pozwalają ocenić zakres bez zgadywania. Brak odpowiedzi na któreś pytanie też jest użyteczną informacją.

1. Wersja Medusy, jeśli projekt już działa, oraz lista własnych modułów i zmian.
2. Model katalogu: czy dwóch sprzedawców może oferować ten sam towar.
3. Lista ról po stronie sprzedawcy i operatora.
4. Statusy sprzedawcy i reguła publikacji ofert.
5. Przebieg jednego zamówienia z pozycjami od dwóch sprzedawców, od koszyka do wysyłki.