Joom¶

Joom to globalny marketplace skupiony na cross-border (głównie Europa Zachodnia + Azja). Integracja działa, ale moderacja Joom jest nieprzewidywalna.

Status delivery¶

🟠 Częściowe — kod podpięty i działa, ale realna sprzedaż blokowana przez Joom moderation (TASK-282).

Funkcja	Status
OAuth (auth code + refresh)	✅
Pobieranie ofert	✅
Wystawianie pojedyncze	✅
Wystawianie rodzin (group_by_family)	✅
`(cennik1 + cennik2) × współczynnik`	✅ flow listingowy. `update_offer.ts` wciąż używa `cennik1` only (deferred z TASK-290 — strict mirror Allegro reference scope).
Auto-retry	⚪

Setup — podłączenie konta Joom¶

Marketplace → Konfiguracja → Joom → Dodaj konto.
Wpisz Etykietę. Joom nie ma środowiska sandbox — wszystko leci na produkcję.
Kliknij Autoryzuj w Joom — przekierowanie do logowania Joom Merchant.
Zaloguj się kontem sprzedawcy Joom Merchant.
Joom zwróci code, panel wymieni go na parę access/refresh-token.

Mapowanie kategorii i atrybutów¶

W Konfiguracja → Joom ustawiasz:

Joom category tree mapping per rodzina — Joom ma własne drzewo kategorii w stylu chińskich marketplace (głębokie, z kilkoma poziomami).
Attribute templates — Joom wymaga określonych atrybutów per kategoria (Material, Country of Origin, Hazmat, …).

Wystawianie¶

Pojedynczy produkt¶

Marketplace → Oferty → Joom, wybierz konto i rodzinę.
Kliknij Wystaw dla SKU.
Panel:
liczy cenę przez (cennik1 + cennik2) × współczynnik,
buduje atrybuty z mapowania,
wysyła POST /api/v3/products przez create_or_update.ts,
oferta wchodzi w stan moderacji Joom (PENDING_REVIEW) — może to potrwać kilka dni.

Rodzina¶

Joom wspiera warianty przez SKU-level grouping. Panel używa group_by_family.ts aby:

Utworzyć produkt-parent w Joom z atrybutami wspólnymi dla rodziny.
Przypisać SKU jako variants z size / color / itd.
Wystawić jako jedna oferta wielowariantowa.

Cenniki¶

Reguła	Status
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik` przy listingu	✅
`(cennik1 + cennik2) × współczynnik` przy `update_offer`	🟠 — używa `cennik1` only (deferred)

Cennik2 w update_offer jest follow-upem

Listing nowej oferty + bulk re-listing korzystają z cennika2 poprawnie. Tylko ścieżka „edytuj istniejącą ofertę" jest pominięta — tutaj musisz wycofać i wystawić ponownie, jeśli chcesz przeliczyć cennik2 dla istniejącego listingu.

Stany ofert¶

Status (panel)	Co znaczy w Joom
`pending`	Wysłano payload, czekamy na response
`listed`	Joom przyjął i przeszedł moderację (`APPROVED` / `LIVE`)
`failed`	Walidacja odrzuciła (atrybuty / kategoria / zdjęcia)
`pending` (długo)	Często oznacza moderację Joom — patrz Edge cases
`removed`	Joom zdjął ofertę (np. polityka kategorii)

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Refresh tokenu OAuth	co 50 minut
Snapshot ofert (`pull_offers`)	uruchamiane z UI + cron

Edge cases / known gotchas¶

Moderacja Joom potrafi blokować bez wyjaśnienia

Joom ma własną wewnętrzną moderację, która może odrzucić ofertę bez konkretnego błędu („not approved" w last_remote_sync_at to wszystko, co dostaniesz). Najczęstsze przyczyny: zdjęcia z dopiskami / logo, nazwa produktu z gwarancją (np. „best ever"), kategoria zastrzeżona w danym kraju.

Owner-action issues J1140 / J1430

Te dwa kody błędu Joom oznaczają, że konto sprzedawcy musi przejść dodatkową weryfikację po stronie Joom (KYC, dane podatkowe). To nie jest do naprawienia z poziomu panelu — właściciel musi zalogować się do Joom Merchant i uzupełnić wymagane dokumenty. Szczegóły: TASK-282.

Joom blokuje silnie nasycone kategorie

Joom ogranicza nowych sprzedawców w popularnych kategoriach (np. elektronika, kosmetyki) — wymaga „uzasadnienia biznesowego" przed publikacją. Dla naszego asortymentu (akcesoria dla psów) jest to zwykle bezproblemowe, ale przy rozszerzaniu w nowe kategorie spodziewaj się tego.

Wsparcie Joom Merchant

Joom ma support w panelu sprzedawcy — w razie nieoczywistego odrzucenia warto otworzyć ticket bezpośrednio u nich (panel nie ma dostępu do ich kanału support).

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized`	Reauthorize konto.
Ofeta `pending` >24 h	Moderacja Joom. Czekaj do 5 dni roboczych.
`J1140` / `J1430`	KYC po stronie Joom — właściciel uzupełnia dokumenty w Joom Merchant.
`validation_error: image_has_text`	Zdjęcia mają znak wodny lub tekst. Wymień w BL.
`category_restricted`	Joom blokuje publikację w tej kategorii. Wybierz inną lub poproś Joom o approval.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings. remote_product_id = Joom product ID.
Główne skrypty: windmill/f/marketplace/joom/create_or_update.ts, group_by_family.ts, report_joom_results.ts, update_offer.ts (cennik2 deferred).
Scheduler: f/marketplace/joom/refresh_token.schedule.yaml (50 min).