Amazon¶

Amazon SP-API jest podpięty i działa, ale ze zrozumieniem polityki Amazona: każdy rynek = osobne konto sprzedawcy.

Status delivery¶

🟠 Częściowe — pełna integracja na Amazon.PL, inne rynki czekają na osobne konta sprzedawcy po stronie Amazona (Forgejo #20).

Funkcja	Status
OAuth (Login with Amazon + SP-API)	✅
Pobieranie ofert (listings)	✅
Wystawianie pojedyncze	✅
Wystawianie rodzin (parent/child)	🟠 (`publish_group` bez cennika2)
`(cennik1 + cennik2) × współczynnik`	✅ flow serwerowy (z wyjątkiem variant-publisher)
Auto-retry	⚪
Synchronizacja zwrotów (`returns`)	✅ co 3 h
Obsługa A-to-Z claims	⚪ poza zakresem oferty
Wsparcie wielu rynków (DE, FR, IT, …)	❌ wymaga osobnego konta sprzedawcy per rynek

Setup — podłączenie konta Amazon¶

Po stronie Amazona

Założenie konta sprzedawcy w Amazon Seller Central jest po stronie właściciela — wymaga weryfikacji firmy, podatkowej, bankowej. To wielodniowy proces. Panel nie rozpoczyna tej ścieżki.

Gdy konto sprzedawcy jest gotowe:

Marketplace → Konfiguracja → Amazon → Dodaj konto.
Wpisz Etykietę (np. „Amazon PL — buyspace") i Marketplace ID (np. A1C3SOZRARQ6R3 dla PL, A1PA6795UKMFR9 dla DE).
Kliknij Autoryzuj w Amazon — przekierowanie do Login with Amazon.
Zaloguj się kontem Seller Central, zaakceptuj uprawnienia SP-API (Catalog, Listings, Orders, Reports, Notifications).
Amazon przekieruje z powrotem do panelu z selling_partner_id + code. Panel wymieni kod na refresh-token i aws_access_key (LWA + SP-API to dwa zbliżone, ale osobne kanały — konfigurujemy oba).
Sprawdź w liście kont: status valid, Last refreshed w ciągu ostatnich godzin.

Per-rynek konto¶

Dodanie kolejnego rynku Amazon (DE, FR, IT, ES, UK, NL, …) wymaga identycznej procedury, ale:

a) Założenia osobnego konta sprzedawcy w danym kraju Amazon (decyzja Amazona, nie panelu).
b) Drugiej autoryzacji OAuth w panelu jako nowe konto z innym Marketplace ID.
c) Konfiguracji per-rynek: waluta (EUR/GBP), VAT, regulaminy zwrotów Amazona w lokalnym języku, polityki wysyłki w danym kraju.

→ Pełen kontekst: FAQ #20.

Wystawianie¶

Pojedynczy produkt (LISTING_OFFER_ONLY)¶

Najczęściej używana ścieżka — produkt już istnieje w katalogu Amazon (ASIN), my dodajemy tylko ofertę:

Marketplace → Oferty → Amazon, wybierz konto.
Wybierz tag rodziny i SKU.
Kliknij Wystaw.
Panel:
dolicza cenę przez (cennik1 + cennik2) × współczynnik,
buduje minimalny payload LISTING_OFFER_ONLY (tylko our_price, quantity, condition, merchant_shipping_group),
wysyła PUT /listings/2021-08-01/items/{seller_id}/{sku},
po sukcesie zapisuje remote_product_id = ASIN, status=listed.

Pełny produkt z atrybutami¶

Jeśli ASIN nie istnieje, panel używa build_attributes.ts → publish.ts (pełny payload z atrybutami z product_type):

Panel pobiera Amazon productType (PET_BED, BEDDING, …) — mapowanie kategorii rodziny → productType jest w Konfiguracji konta.
Buduje payload zgodny ze schematem JSON dla danego productType.
Wysyła PUT — Amazon waliduje payload względem schematu i albo akceptuje (ACCEPTED/VALID), albo zwraca listę violations.
W razie violations status = failed, w wątku oferty masz pełen error_message.

Rodzina (parent/child variations)¶

🟠 Funkcjonalność jest podpięta (publish_group.ts), ale ma znane ograniczenie:

Cennik2 nie jest stosowany w publish_group

Dashboard wysyła price_group_id_2 do publish_group, ale ten flow ma własny inline-resolver ceny zamiast dzielonego resolveCombinedPriceBase. W praktyce: ceny w wariantowych publikacjach Amazon liczą się po starej regule cennik1 × współczynnik. Pojedyncze listingi Amazon (LISTING_OFFER_ONLY i pełne) honorują cennik2. Zaplanowane do naprawy w bug-fix mode.

Cenniki¶

Reguła	Status flow serwerowego
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik` (pojedynczy)	✅
`(cennik1 + cennik2) × współczynnik` (warianty / publish_group)	🟠 — używa `cennik1` only
Per-konto `merchant_shipping_group`	✅ ustawiane w Konfiguracji

→ Patrz model cenowy.

Stany ofert¶

Amazon używa kombinacji status (ACTIVE, INACTIVE) i submission_status (ACCEPTED, INVALID, IN_PROGRESS). Panel mapuje to na własne:

Status (panel)	Co znaczy w Amazon
`pending`	Wysłano `PUT /listings`, czekamy na callback `PROCESSING_STATUS`
`listed`	`submission_status=ACCEPTED` + `status=ACTIVE`
`failed`	`submission_status=INVALID` (lista `issues` w `error_message`)
`updating`	Edycja istniejącego listingu w toku
`removed`	Listing aktywnie wycofany lub Amazon zsunął offer (np. polityka cenowa)

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Refresh tokenu OAuth	co 50 minut
Pobieranie zwrotów (`fetchers/returns`)	co 3 godziny
Snapshot ofert (`pull_offers`)	uruchamiane z UI + cron

Edge cases / known gotchas¶

A-to-Z claims poza zakresem

Amazon ma osobny mechanizm reklamacji „A-to-Z Guarantee", w którym kupujący eskaluje sprawę bezpośrednio do Amazona. Panel nie obsługuje A-to-Z claims — to wymaga osobnej integracji z Reports API i ręcznego workflow. Obecnie A-to-Z claims muszą być rozpatrywane bezpośrednio w Seller Central.

Polityka cenowa Amazona może deaktywować ofertę

Amazon ma wbudowane progi „buy box eligibility" i potrafi automatycznie zsuwać ofertę jeśli cena jest „zbyt wysoka" lub „zbyt niska" względem rynku (zwłaszcza dla ASINów z konkurencją). Panel pokaże taką ofertę jako removed po najbliższej synchronizacji — sprawdź error_message (OFFER_PRICE_TOO_HIGH, OFFER_PRICE_LANDED_NOT_COMPETITIVE).

Schemat productType bywa zaskakujący

Każdy productType ma własny JSON schema (kilkadziesiąt — kilkaset wymaganych pól). Panel nie zgaduje brakujących wartości — jeśli rodzina nie ma model_name, country_of_origin, weight_unit_of_measure, dostaniesz failed z listą violations. Uzupełnij brakujące dane w BaseLinkerze (extra fields per produkt) lub w mapowaniu kategorii rodziny.

Amazon.PL podpięte, inne rynki gotowe technicznie

Cała logika SP-API jest generic po stronie panelu — wystarczy dodać konto z innym marketplace_id i autoryzować. Nie ma żadnych dodatkowych zmian kodu wymaganych do uruchomienia DE / FR / IT / ES / UK / NL. Wąskie gardło to konto sprzedawcy po stronie Amazona.

Walidacja przed publikacją

Dla pełnych payloadów (nie LISTING_OFFER_ONLY) zalecamy najpierw uruchomić build_attributes jako dry-run w trybie deweloperskim — panel pokaże, czy schemat jest spełniony, zanim trafi do Amazona. (Ta funkcjonalność jest dostępna tylko z poziomu Windmill, nie z UI.)

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized`	Refresh-token wygasł. Konfiguracja → Amazon → Reauthorize dla danego konta.
`MISSING_ATTRIBUTE: <pole>`	Brak wymaganego atrybutu dla `productType`. Uzupełnij w BaseLinkerze (extra fields) i wystaw ponownie.
`OFFER_PRICE_TOO_HIGH`	Amazon uznał cenę za zbyt wysoką (polityka). Obniż współczynnik lub zaakceptuj brak listingu.
`INVALID_PRODUCT_TYPE`	Mapowanie rodziny → productType jest błędne. Sprawdź Konfiguracja → Amazon → Mapowanie kategorii.
`LISTING_OFFER_ONLY: ASIN_NOT_FOUND`	ASIN nie istnieje na docelowym rynku. Wystaw pełen payload (build_attributes) zamiast offer-only.
Wszystkie oferty `failed` po dodaniu konta	Amazon wymaga, żeby `client_id` aplikacji panelu był zatwierdzony przez Twoje konto sprzedawcy. Sprawdź Apps & Services → Develop Apps.
Cennik2 nie zostawia śladu w cenie wariantów	Znane: `publish_group` używa starej reguły. Wystaw pojedynczo lub poczekaj na fix.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings (Convex). remote_product_id = ASIN.
Główne skrypty: windmill/f/marketplace/amazon/publish.ts (single), publish_group.ts (variants), build_attributes.ts, update_listing.ts, delete_listing.ts.
Schedulery: refresh_token.schedule.yaml (50 min), fetchers/returns.schedule.yaml (3 h).
SP-API regions skonfigurowane per konto (extra.region = eu-west-1 dla EU rynków).