eBay¶

eBay jest podpięty z pełną obsługą wariantów (Inventory Item Group). Wymaga jednego dodatkowego kroku konfiguracyjnego po stronie konta sprzedawcy: Business Policies.

Status delivery¶

✅ Pełne — pojedyncze oferty + warianty (12 SKU jednoczesnie potwierdzone na produkcji).

Funkcja	Status
OAuth (auth code + refresh)	✅
Pobieranie ofert	✅
Wystawianie pojedyncze	✅
Wystawianie rodzin (Inventory Item Group)	✅
`(cennik1 + cennik2) × współczynnik`	✅ flow serwerowy (TASK-290.01)
Auto-retry	⚪
Synchronizacja messages / issues / disputes	✅

Setup — podłączenie konta eBay¶

Marketplace → Konfiguracja → eBay → Dodaj konto.
Wybierz Środowisko (production lub sandbox) i Site (eBay PL, DE, UK, …).
Kliknij Autoryzuj w eBay — przekierowanie do logowania eBay.
Zaloguj się kontem sprzedawcy (nie kupującego). Konto musi mieć status Selling enabled po stronie eBay.
Akceptuj uprawnienia (sell.inventory, sell.account, sell.fulfillment, commerce.identity.readonly).
eBay przekieruje z powrotem; panel zapisze parę User Token + Refresh Token.

Wymagane: Business Policies¶

eBay wymaga, żeby każda oferta miała przypisane:

Payment policy — kto przyjmuje płatności (najczęściej eBay Managed Payments).
Return policy — okno zwrotu, kto pokrywa koszt.
Fulfillment policy — czas realizacji, sposób wysyłki, koszty.

Te trzy „polityki" tworzysz w panelu eBay sprzedawcy, nie w naszym panelu (eBay nie udostępnia ich tworzenia przez API). Po utworzeniu — Konfiguracja → eBay → Polityki domyślne wybierasz, której polityki użyć dla danego konta.

Bez Business Policies wystawienie poleci INSUFFICIENT_PERMISSION

eBay zwróci błąd zanim dojdzie do walidacji ceny / kategorii. Sprawdź Business Policies przed pierwszą publikacją.

Wystawianie¶

Pojedynczy produkt¶

Marketplace → Oferty → eBay, wybierz konto.
Wybierz tag rodziny i SKU.
Kliknij Wystaw.
Panel:
tworzy inventoryItem (PUT /sell/inventory/v1/inventory_item/{sku}),
tworzy offer (POST /sell/inventory/v1/offer) z categoryId, polityki, ceną, ilością,
publikuje ofertę (POST /sell/inventory/v1/offer/{offerId}/publish),
po sukcesie zapisuje listing_id (eBay item ID).

Rodzina (warianty)¶

eBay grupuje warianty w Inventory Item Group — to obowiązkowy mechanizm dla rozmiarów/kolorów:

Panel tworzy inventoryItemGroup (np. family_<tag>).
Każdy SKU w rodzinie staje się inventoryItem z aspects (rozmiar, kolor) zgodnymi z aspectsImageVariesBy.
Tworzy się jeden offer per rodzina, ale linkujący do inventoryItemGroupKey.
Publikacja (publishByInventoryItemGroup) — eBay wystawia pojedynczy listing wielowariantowy.

aspects musi się zgadzać między SKU a rodziną

Wszystkie SKU w rodzinie muszą mieć identyczny zestaw aspektów (np. każdy SKU musi deklarować Size i Color). Jeśli jeden SKU pominie aspekt, eBay zwróci błąd aspectsImageVariesBy mismatch. Naprawiamy to w bug-fix mode (TASK-284).

Cenniki¶

Reguła	Status
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik`	✅ (TASK-290.01)
Per-konto polityki wysyłki / zwrotów	✅ via Business Policies

Stany ofert¶

Status (panel)	Co znaczy w eBay
`pending`	InventoryItem utworzony, czekamy na publish
`listed`	Offer opublikowany, `listingStatus=ACTIVE`
`failed`	Walidacja eBay odrzuciła
`updating`	Edycja w toku
`removed`	Listing zakończony lub wycofany

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Refresh tokenu OAuth	co 1 godzinę
Pobieranie wiadomości (`fetchers/messages`)	co 5 minut
Pobieranie issues / sporów	co 10–15 minut
Pobieranie payment disputes	co 15 minut
Pobieranie resolutions	co 15 minut

Edge cases / known gotchas¶

Odrzucanie z powodu zdjęć

eBay wymaga zdjęć w jakości min. 500×500 px, na białym tle, bez znaków wodnych. Jeśli zdjęcia produktu w BaseLinkerze są niskiej jakości, oferta poleci jako failed z image_too_small lub image_has_text. Uzupełnij zdjęcia w BL i wystaw ponownie.

VAT na ofertach poza UK / EU

Sprzedaż do UK lub poza EU wymaga konfiguracji VAT na poziomie konta sprzedawcy eBay i może wymagać EORI. To nie jest problem panelu — eBay zwróci seller_account_not_eligible_for_listing_in_country jeśli konto nie spełnia wymogów.

eBay site vs marketplace

Każde konto eBay jest powiązane z jednym site (EBAY_PL, EBAY_DE, EBAY_GB, …). Aby sprzedawać na innym rynku eBay, dodajesz drugie konto z innym site — analogicznie do Amazona, ale bez wymogu osobnego konta sprzedawcy (jedno konto eBay może działać na wielu rynkach, jeśli Business Policies są skonfigurowane per rynek).

Listingi rzadko psują się same

eBay nie ma „algorytmicznej deaktywacji" jak Amazon — raz opublikowana oferta zostaje, dopóki nie skończy się jej listingDuration (zwykle GTC = until cancelled). Jedyne co je skraca: out-of-stock (eBay automatycznie zmienia quantityAvailable=0 jeśli zsynchronizujesz 0 z BL).

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized`	Reauthorize konto.
`INSUFFICIENT_PERMISSION`	Brakuje Business Policies. Idź do panelu eBay i utwórz payment/return/fulfillment policies.
`aspectsImageVariesBy mismatch`	SKU w rodzinie mają różne zestawy aspektów. Wyrównaj w BL. (TASK-284)
`listing_id` w panelu, ale na eBay „zakończona"	eBay zakończył ofertę (np. zero stock przez >30 dni). Refresh now zsynchronizuje.
`category not eligible for listing`	Wybrana kategoria wymaga uprawnień (np. media, alkohol). Wybierz inną kategorię lub wystąp do eBay o uprawnienia.
Oferta `pending` ponad godzinę	eBay Inventory API używa async-flow przez ~30 s; ponad godzinę = bug. Sprawdź `/marketplace/history`.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings + ebay_variant_groups (dla wariantów).
Główne skrypty: windmill/f/marketplace/ebay/publish_group.ts, upsert_inventory.ts, update_offer.ts, withdraw_offer.ts.
Schedulery: refresh_token.schedule.yaml (1 h), fetchers/messages.schedule.yaml (5 min), fetchers/issues.schedule.yaml (10 min), fetchers/payment_disputes.schedule.yaml (15 min), fetchers/resolutions.schedule.yaml (15 min).