Allegro¶

Najgłębiej zintegrowana platforma w panelu. Allegro było pierwsze i jest „kanałem referencyjnym" — wszystkie pozostałe integracje były pisane wzorowane na Allegro.

Status delivery¶

✅ Pełne — wystawianie pojedyncze i rodziny, pobieranie ofert, automatyczne odświeżanie tokenów, auto-retry przy PARAMETER_MISMATCH, GPSR/responsibleProducer, indeksowane cenniki wysyłki per karton.

Funkcja	Status
OAuth (auth code + refresh)	✅
Pobieranie ofert	✅
Wystawianie pojedyncze	✅
Wystawianie rodzin (warianty)	✅
`(cennik1 + cennik2) × współczynnik`	✅ flow serwerowy 1:1
Auto-retry przy `PARAMETER_MISMATCH`	✅ (TASK-220)
afterSalesServices per konto	✅ (TASK-224)
Cenniki wysyłki indeksowane kartonami	✅ (TASK-224)
GPSR safety_text per rodzina	✅ (TASK-321.06)
Mark-as-read po odpowiedzi (CS)	✅

Setup — podłączenie konta Allegro¶

Otwórz Marketplace → Konfiguracja → Allegro w bocznym menu.
Klikinj Dodaj konto. Pojawi się formularz z polem Etykieta (czytelna nazwa, np. „Allegro PL — buyspace") i Środowisko (production lub sandbox).
Po zapisaniu zobaczysz przycisk Autoryzuj w Allegro — kliknięcie otwiera w nowej karcie ekran logowania Allegro.
Zaloguj się kontem Allegro właściciela sklepu (nie operatora) — Allegro wiąże refresh-token z tą tożsamością.
Allegro pyta o uprawnienia (allegro:api:profile:read, allegro:api:sale:offers:write, allegro:api:sale:offers:read, allegro:api:disputes, allegro:api:messaging, allegro:api:billing i kilka pochodnych). Zaakceptuj wszystkie — bez tego niektóre funkcje przestają działać.
Po zatwierdzeniu Allegro przekieruje z powrotem do panelu z code w URL. Panel automatycznie wymieni code na parę access/refresh-token i zapisze ją zaszyfrowaną w bazie.
W liście kont status zmieni się na valid z datą Last refreshed. Od tego momentu konto jest gotowe do użycia.

Reauthorize bez zerowania konta

Jeśli token zostanie unieważniony (np. właściciel zmienił hasło Allegro), kliknij Reauthorize przy koncie — przejdziesz przez ten sam OAuth-flow, ale konto i wszystkie reguły cenowe pozostają nietknięte. Tylko nowa para tokenów się zapisze.

Per-konto ustawienia listy¶

W tej samej zakładce konfiguracji Allegro ustawiasz reguły specyficzne dla konta:

Cennik1 + Cennik2 + Współczynnik — patrz model cenowy.
afterSalesServices — szablon zwrotów / reklamacji / gwarancji per konto. Allegro wymaga, żeby każda oferta wskazywała ID szablonu.
Cennik wysyłki indeksowany kartonami — mapowanie SKU → karton (S/M/L/XL) + tabela kosztów wysyłki dla każdego rozmiaru kartonu. Panel sam dobiera koszt wysyłki przy wystawianiu.
safety_text_by_family — verbatim polski tekst GPSR per rodzina produktów. Bez wpisu używamy domyślnego tekstu „dog-bed" (historycznego). Zalecamy uzupełnić dla każdej rodziny innej niż leżanki dla psów.
Kategoria domyślna per rodzina — Allegro wymaga categoryId dla każdej oferty; UI pozwala ustawić mapowanie raz dla całej rodziny.

Wystawianie pojedyncze i rodziny¶

Pojedynczy produkt¶

Marketplace → Oferty → Allegro.
Wybierz konto Allegro u góry (jeśli masz więcej niż jedno).
Wybierz tag rodziny w lewej kolumnie.
Znajdź konkretny SKU w tabeli i kliknij Wystaw.
Panel:
dolicza cenę: (cennik1 + cennik2) × współczynnik,
zaciąga categoryId i parametry kategorii ze szablonu,
dobiera safety_text (per-rodzina lub fallback),
tworzy ofertę przez POST /sale/offers,
jeśli Allegro odpowie PARAMETER_MISMATCH, panel automatycznie dociąga proponowane wartości parametrów (product change proposal) i ponawia.
Po sukcesie status w wątku zmienia się na listed + zapisujemy remote_publication_status (np. ACTIVATING) i last_remote_sync_at.

Rodzina (warianty)¶

Allegro wspiera grupy ofert (oferty z parametrami Rozmiar / Kolor). Panel:

Czyta wszystkie SKU z TAGu rodziny.
Tworzy product w katalogu Allegro (raz per rodzina — na jego podstawie wszystkie warianty łączy się w grupę).
Wystawia oferty per SKU, każdą podpiętą do tego samego produktu.
Allegro samo grupuje oferty na liście kupujących.

Allegro wymaga zatwierdzenia produktu

Pierwsze wystawienie rodziny zwykle uruchamia ścieżkę change proposal — Allegro pyta, czy nowy produkt z naszymi parametrami może zostać dodany do katalogu Allegro. Status przejściowy: PENDING_CHANGE_PROPOSAL. Może to potrwać od kilku minut do kilku godzin po stronie Allegro. Panel sam wykryje przyjęcie i odpali process_products.

Cenniki¶

Reguła	Status flow serwerowego
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik`	✅ end-to-end (TASK-269)
Cenniki wysyłki indeksowane kartonami	✅ (TASK-224)
Per-konto afterSalesServices	✅

Zmiana współczynnika lub wybór cennika2 w UI nie odpalają automatycznej re-wyceny istniejących ofert. Aby przeliczyć aktywne oferty po zmianie reguły:

Marketplace → Oferty → Allegro, wybierz rodzinę.
Zaznacz oferty (checkbox).
Akcje grupowe → Re-wystaw / Aktualizuj cenę.

Stany ofert¶

Status (panel)	Co znaczy w Allegro	Przyczyna
`pending`	Wysłano `POST /sale/offers`, czekamy na odpowiedź	Normalny stan przelotny (sekundy)
`listed`	Allegro zaakceptowało; oferta `ACTIVE` lub `ACTIVATING`	Sukces
`failed`	Allegro odrzucił	Patrz `error_message` w wątku
`updating`	Trwa edycja istniejącej oferty	Normalny przelotny
`conflict`	Inne konto Allegro już ma listing tego SKU	Operator decyduje, które wygrywa

Allegro dodatkowo ma własne statusy oferty (ACTIVE, ENDED, INACTIVE, INACTIVATED, …) — trzymamy je w remote_publication_status. Filtr „Wszystkie wystawione" w sekcji Oferty respektuje te statusy (Forgejo #28).

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Refresh tokenu OAuth	co 11 godzin
Pobieranie zgłoszeń klienta (`fetchers/issues`)	co 10 minut
Snapshot ofert (`pull_offers`)	uruchamiane z UI + cron per konto

Logi → panel.aiofactory.pl/marketplace/history (filtruj platform=allegro). Każdy przebieg ma identyfikator zadania Windmill — link otwiera szczegółowy log.

Edge cases / known gotchas¶

GPSR / responsibleProducer wymagane od 13 grudnia 2024

Allegro wymaga, by każda oferta miała pole safetyInformation (verbatim polski tekst zgodności GPSR). Bez tego oferta nie zostanie zaakceptowana w 2025+. Panel ma per-rodzina mapę safety_text_by_family w konfiguracji konta — wpisz polski tekst zgodności dla każdej rodziny produktów. Bez wpisu używamy historycznego fallbacku „leżanki dla psów" — co jest niepoprawne dla każdej innej kategorii.

PARAMETER_MISMATCH po pierwszym wystawieniu rodziny

Pierwsza próba wystawienia nowej rodziny czasem rzuca PARAMETER_MISMATCH — Allegro twierdzi, że jeden lub więcej parametrów (np. Producent, Kolor dominujący) nie pasuje do oczekiwanych wartości w katalogu. Panel obsługuje to automatycznie (TASK-220) — wysyła change proposal i ponawia. Jedyne, czego potrzebujesz, to chwila cierpliwości (kilka minut do kilku godzin).

afterSalesServices musi być utworzone w Allegro

Allegro wymaga, by szablony zwrotów/reklamacji/gwarancji istniały w panelu Allegro przed wystawieniem oferty. Panel ich nie tworzy — odczytuje ID. Jeśli właściciel zmieni szablony w Allegro, zaktualizuj ich ID w Konfiguracji konta w panelu.

Konflikty między kontami Allegro

Jeśli masz dwa konta Allegro (np. PL główne + PL drugie), panel wykryje, gdy ten sam SKU jest wystawiony na obu — i oznaczy oba listingi statusem conflict. Użyj Marketplace → Konfiguracja → Konflikty, aby wybrać, które konto „wygrywa" (drugie zostanie wycofane przy najbliższej publikacji).

Pomoc oferty: Refresh now

Pojedyncza oferta może rozjechać się ze stanem panelu, jeśli ktoś zmieni coś w Allegro ręcznie (np. zakończy ofertę). W wątku oferty kliknij Refresh now — panel pobierze aktualny stan z Allegro i go zapisze.

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized` przy wystawianiu	Token wygasł i refresh nie wstrzelił się. Konfiguracja → Allegro → Reauthorize.
`403 Forbidden — missing scope`	Brak uprawnienia OAuth. Zrób Reauthorize i upewnij się, że żaden checkbox uprawnień nie jest odznaczony.
`PARAMETER_MISMATCH` na nowej rodzinie	Auto-retry powinien zadziałać sam (TASK-220). Jeśli po 30 min wciąż `failed` — zgłoś w Forgejo z `family_key` i `categoryId`.
`safetyInformation: required`	Brak wpisu w `safety_text_by_family`. Dodaj polski tekst GPSR dla tej rodziny w Konfiguracja → Allegro.
`categoryId not found`	Konfiguracja konta nie ma mapowania rodziny → kategorii Allegro. Uzupełnij.
Oferta `listed` w panelu, ale na Allegro „zakończona"	Klient lub Allegro zakończył ofertę poza panelem. Kliknij Refresh now w wątku oferty.
Cennik2 w UI ustawiony, ale cena na Allegro liczona po starym	Zwykle rozjazd snapshotu. Wykonaj Akcje grupowe → Aktualizuj cenę dla rodziny.
Wystawianie zwraca `PRODUCT_CHANGE_PROPOSAL_PENDING`	Normalny stan — Allegro modeluje produkt w katalogu. Czekaj 30 min — 2 h, status zmieni się sam.

→ Reszta typowych problemów: diagram diagnostyczny.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings (Convex). Pole remote_publication_status trzyma status Allegro 1:1.
Główne flowy: windmill/f/marketplace/allegro/list_all_products.flow/, list_selected_products.flow/, process_products.ts, update_offer.ts, propose_product_change.ts.
GPSR resolver: windmill/f/marketplace/allegro/lib/listing.ts (safety_text_by_family + fallback).
Schedulery: f/marketplace/allegro/refresh_token.schedule.yaml (11 h), f/marketplace/allegro/fetchers/issues.schedule.yaml (10 min).