Erli¶

Erli to polski marketplace fokusowany na rękodzieło i unikatowe produkty. Integracja jest w pełni operacyjna, z mapowaniem kategorii i atrybutów per rodzina.

Status delivery¶

✅ Pełne — pojedyncze, rodziny, cennik2 — potwierdzone na produkcji.

Funkcja	Status
OAuth (auth code + refresh)	✅
Pobieranie ofert	✅
Wystawianie pojedyncze	✅
Wystawianie rodzin (warianty)	✅
`(cennik1 + cennik2) × współczynnik`	✅ flow serwerowy (TASK-290)
Auto-retry	⚪
Synchronizacja zgłoszeń	✅ co 10 min

Setup — podłączenie konta Erli¶

Marketplace → Konfiguracja → Erli → Dodaj konto.
Wpisz Etykietę + wybierz Środowisko (production / sandbox).
Kliknij Autoryzuj w Erli — przekierowanie do logowania Erli.
Zaloguj się kontem sprzedawcy Erli (musisz mieć aktywny status sprzedawcy w panelu Erli).
Erli zwróci code, panel wymieni go na refresh-token.

Mapowanie kategorii¶

Erli ma własne drzewo kategorii (z elementami unikalnymi dla rękodzieła — np. Ręcznie szyte / Customizowane). W Konfiguracja → Erli → Mapowanie kategorii ustawiasz dla każdej rodziny produktów:

categoryId Erli,
atrybuty per kategoria (Erli ma własne attribute keys, np. craft_type, materials),
czy produkt to handmade / custom.

Mapowanie raz per rodzina

Mapowanie ustawiasz raz dla całego TAGu. Wszystkie SKU w rodzinie dziedziczą tę samą kategorię i bazowe atrybuty.

Wystawianie¶

Pojedynczy produkt / rodzina¶

Erli traktuje pojedynczy produkt i rodzinę identycznie po stronie API — używamy create_or_update.ts w obu przypadkach:

Marketplace → Oferty → Erli, wybierz konto i tag rodziny.
Kliknij Wystaw (per SKU lub bulk dla rodziny).
Panel:
dolicza cenę przez (cennik1 + cennik2) × współczynnik,
buduje atrybuty z mapowania kategorii + extra_fields z BaseLinkera,
wysyła POST /v1/offers (lub PUT jeśli SKU już istnieje),
po sukcesie zapisuje remote_product_id = Erli offer ID.

Cenniki¶

Reguła	Status
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik`	✅ (TASK-290)

Stany ofert¶

Status (panel)	Co znaczy w Erli
`pending`	Wysłano `POST /offers`, czekamy
`listed`	Erli zaakceptowało, oferta `ACTIVE`
`failed`	Erli odrzucił (atrybuty / cena / kategoria)
`updating`	`PUT /offers/{id}` w toku
`removed`	Sprzedawca lub Erli zakończył ofertę

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Refresh tokenu OAuth	przy każdym call (Erli token żyje krótko)
Pobieranie zgłoszeń klienta (`fetchers/issues`)	co 10 minut
Snapshot ofert (`pull_offers`)	uruchamiane z UI + cron

Edge cases / known gotchas¶

Erli nie cierpi pustych atrybutów

Erli waliduje payload sztywno — jeśli rodzina ma w mapowaniu zadeklarowany atrybut materials, ale konkretny SKU w BaseLinkerze nie ma tego pola, Erli zwróci validation_error. Uzupełnij materials w BL dla każdego SKU w rodzinie.

Orphan listings (TASK-281)

W historii projektu były orphan rows w tabeli marketplace_listings (Erli marketplace_id brakujący po stronie panelu, ale oferta istnieje na Erli). Backfill został wykonany jednorazowo przez mutation marketplace/listings:setMarketplaceId. Nie powinno się to powtórzyć — ale jeśli zauważysz ofertę „znikającą" z UI mimo że jest na Erli, zgłoś bug w Forgejo.

Erli wspiera handmade flagę

Jeśli zaznaczysz produkt jako handmade w mapowaniu, Erli pokaże ofertę z odznaką „Ręcznie wykonane" — co realnie poprawia konwersję na tej platformie. Skorzystaj.

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized`	Reauthorize konto.
`validation_error: missing attribute X`	Uzupełnij `X` w BL extra fields lub skoryguj mapowanie.
`category_not_found`	Erli zaktualizował drzewo kategorii. Sprawdź Konfiguracja → Erli → Mapowanie kategorii.
Listing widoczny w panelu, ale nie na erli.com	Czasem Erli moderuje pierwszą ofertę nowego sprzedawcy ręcznie. Czekaj 24–48 h.
Ceny nie aktualizują się po zmianie współczynnika	Wykonaj Akcje grupowe → Aktualizuj cenę.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings. remote_product_id = Erli offer ID.
Główne skrypty: windmill/f/marketplace/erli/create_or_update.ts, update_offer.ts, report_erli_results.ts.
Scheduler: f/marketplace/erli/fetchers/issues.schedule.yaml (10 min). Erli nie ma refresh_token.schedule — token odświeżamy w locie.