Source setup — podpinanie źródeł CS¶
Każde źródło zgłoszeń (Allegro, eBay, Amazon, Erli, Joom, Temu, WooCommerce, Email) wymaga jednorazowej konfiguracji, żeby panel mógł odbierać wiadomości / spory / zwroty. Ten dokument prowadzi przez to per platforma.
Krótko
- Marketplace (Allegro / eBay / Amazon / Erli / Joom / Temu / WooCommerce) — konfiguracja przez OAuth. Te same konta obsługują CS i Listings — jedno logowanie wystarczy do obu modułów.
- Email (Gmail / Mailcow) — w
Marketplace → Konfiguracja → Konta e-mail. Mailcow = adres + hasło IMAP, Gmail = adres + 16-znakowe hasło aplikacji (z 2FA). - Częstotliwości pobieracza: email co 5 min, Allegro / eBay issues / Erli / WooCommerce co 10 min, eBay messages co 5 min, Amazon returns co 3 godziny.
- Wszystkie pobieracze są read-only — patrz § Polityka read-only.
Email — Gmail (multi-account)¶
Najczęstszy przypadek: kilka skrzynek Gmail (np. support@aiofactory.pl, reklamacje@aiofactory.pl, kingdog@…) → wszystkie wpadają do tej samej skrzynki CS, ale każda dostaje swojego opiekuna według reguł przydziału.
Wymagania wstępne¶
- Konto Google z 2FA (uwierzytelnianie dwuskładnikowe). Bez 2FA nie wygenerujesz hasła aplikacji.
- Etykiety w Gmailu już zaplanowane i utworzone (np.
Reklamacje,Zwroty,Faktury). Etykiety pobiera się dopiero po dodaniu konta — patrz krok 5.
Krok 1 — wygeneruj hasło aplikacji w Gmail¶
- Otwórz
myaccount.google.com/apppasswords. Strona wymaga aktywnego 2FA — jeśli nie masz, włącz 2FA wmyaccount.google.com/securityi wróć tu. - W polu „App name" wpisz np. AIO Factory CS.
- Klikasz Create. Google wyświetla 16-znakowe hasło rozdzielone spacjami (np.
xqab cdef ghij klmn). - Skopiuj to hasło natychmiast — Google pokazuje je tylko raz. Spacje możesz zostawić; panel je sam zignoruje.
To NIE jest Twoje hasło Gmail
Hasło aplikacji jest osobnym sekretem, ważnym tylko dla tej konkretnej integracji. Jeśli zgubisz, wygenerujesz nowe i podmienisz w panelu. Jeśli wylogujesz wszędzie konto Google, hasła aplikacji nie przestają działać — to inny mechanizm uwierzytelniania.
Krok 2 — dodaj konto w panelu¶
- W panelu lewy pasek → Marketplace → Konfiguracja → Konta e-mail (
/marketplace/config/email-accounts). - Po lewej: kafelek „Dodaj konto". Wybierz:
- Dostawca: Gmail.
- Etykieta: np. „Support PL" (to jest tylko nazwa wyświetlana w panelu — nie ma związku z etykietami Gmail).
- Adres e-mail: np.
support@aiofactory.pl. - Hasło aplikacji Google: wklej 16-znakowe hasło z kroku 1.
- Klikasz Dodaj konto.
Krok 3 — weryfikacja SMTP (automatyczna)¶
Panel przed zapisem próbuje:
- Połączyć się z
smtp.gmail.com:587. - Wykonać
STARTTLS. - Zalogować się przez
AUTH LOGINz podanym hasłem aplikacji.
Jeśli któryś krok padnie — zobaczysz konkretny komunikat błędu (np. „SMTP odrzucił hasło dla support@aiofactory.pl: 535 5.7.8 Username and Password not accepted") i konto nie zostanie zapisane. Patrz FAQ #7.
Krok 4 — pobranie etykiet Gmail (automatyczne po pierwszym sync)¶
Bezpośrednio po zapisie panel uruchamia w tle skrypt, który pobiera listę etykiet z Twojej skrzynki Gmail (etykiety używane przez Ciebie ręcznie — Reklamacje, Zwroty, …; etykiety systemowe typu [Gmail]/Wysłane są pomijane).
Zobaczysz w karcie konta sekcję „Etykiety Gmail" z chipami:
Jeśli ich nie ma — kliknij „Odśwież etykiety" na karcie konta. Bywa, że pierwszy sync nie zdąży zakończyć się przed otwarciem widoku.
Krok 5 — reguły przydziału per etykieta¶
W panel.aiofactory.pl/support → zakładka Reguły przydziału dodaj reguły:
| Priorytet | Źródło | Konto | Etykieta Gmail | Opiekun |
|---|---|---|---|---|
| 100 | support@aiofactory.pl |
Reklamacje |
Anna (operator reklamacji) | |
| 110 | support@aiofactory.pl |
Zwroty |
Anna | |
| 120 | support@aiofactory.pl |
(dowolna) | Piotr (operator ogólny) |
Reguły sprawdzane są w kolejności rosnącego priorytetu — pierwsza pasująca wygrywa. Najwęższe reguły (z konkretną etykietą) na górze, catch-all na dole.
Etykieta na wątku, nie na pojedynczej wiadomości
Pobieracz patrzy na etykiety najnowszej wiadomości w wątku (tej, która właśnie wpadła). Jeśli klient pisze 3-krotnie, a etykieta Reklamacje jest tylko na drugiej wiadomości, pobieracz zobaczy ją tylko przy tej drugiej (nowy wątek miał INBOX, więc trafił do catch-all).
Multi-account (kilka skrzynek)¶
Powtórz kroki 1–5 dla każdej skrzynki. Każda dostaje swoje osobne hasło aplikacji, swój wpis w panelu i swoje reguły przydziału.
W zakładce Reguły przydziału kolumna „Konto" pozwala napisać reguły wąsko (np. tylko dla kingdog@…) lub szeroko (dowolne konto Email).
Email — Mailcow (poczta firmowa)¶
Mailcow to system poczty firmowej (mail.aiofactory.pl), używany przez konta @aiofactory.pl / @buyspace.pl. Konfiguracja jest prostsza niż Gmail — nie ma etykiet, nie ma 2FA, jedno hasło używasz i do logowania (SOGo / IMAP / SMTP), i do panelu CS.
Krok 1 — dodaj konto w panelu¶
- Marketplace → Konfiguracja → Konta e-mail → Dodaj konto.
- Wybierz:
- Dostawca: Mailcow.
- Etykieta: np. „Tekstylia".
- Adres e-mail: np.
tekstylia@aiofactory.pl. - Hasło IMAP: to samo, którym logujesz się do
mail.aiofactory.pl/SOGo.
- Klikasz Dodaj konto.
Krok 2 — weryfikacja SMTP¶
Panel próbuje zalogować się do mail.aiofactory.pl:587 z STARTTLS. Jeśli błąd — sprawdź czy hasło na pewno działa do SOGo (mail.aiofactory.pl/SOGo); zmiana hasła w SOGo zmienia hasło wszędzie.
Brak etykiet — co zamiast?¶
Mailcow nie używa „etykiet" w sensie Gmaila. Zamiast tego:
- W zakładce Reguły przydziału pole „Etykieta Gmail" zostaw puste (= „dowolna"; dla Mailcow i tak nie ma znaczenia).
- Jeśli chcesz różnicować, użyj adresu — np.
tekstylia@…→ opiekun Anna,b2b@…→ opiekun Piotr.
Częstotliwość¶
Pobieracz f/support/imap_fetcher chodzi co 5 minut osobno dla każdego dostawcy (jest jeden harmonogram dla Gmaila, jeden dla Mailcow — patrz Dane techniczne).
Allegro¶
Allegro CS pobiera dwa rodzaje zdarzeń:
- Wiadomości z Message Center (klient ↔ sprzedawca, „Centrum sporów" itp.).
- Reklamacje (disputes) — klient otwarł formalny spór („chcę odstąpić od umowy", „produkt niezgodny").
Krok 1 — podpinanie konta Allegro (OAuth)¶
Konfiguracja Allegro znajduje się w sekcji Marketplace → Konfiguracja → Allegro (/marketplace/config/platforms/allegro).
- Klikasz „Dodaj konto Allegro" — panel otwiera ekran logowania Allegro w nowym okienku.
- Logujesz się danymi sprzedawcy Allegro.
- Allegro pyta o uprawnienia — zaznacz wszystkie, w tym Centrum Wiadomości i Centrum Sporów.
- Po akceptacji panel zapisuje token OAuth — widzisz konto w liście z statusem „Połączone".
To samo konto pojawia się też w Listings — patrz Listings → Allegro.
Krok 2 — sprawdzenie pobieracza¶
Marketplace → Konfiguracja → Allegro → zakładka „Synchronizacja" pokazuje datę ostatniego pobierania issues. Domyślnie cron chodzi co 10 minut.
Jeśli „Ostatni sync" to „nigdy" po 15 minutach od dodania konta:
- Sprawdź
/marketplace/history/runsfiltrowane poallegro/fetchers/issues— czy są przebiegisuccess? - Jeśli
failed— zobacz log w Windmill (link w wierszu).
Krok 3 — co panel pobiera, czego nie pobiera¶
✅ Pobiera (read-only): - Wątki Centrum Wiadomości (klient → sprzedawca i odwrotnie). - Spory ze Centrum Sporów + ich status. - Metadane zamówienia (jeśli wątek dotyczy konkretnego zamówienia).
❌ Nie pobiera (do operatora ręcznie): - Wystawienia ofert — patrz Listings. - Akceptacja / odrzucenie zwrotu w Centrum Sporów (Allegro nie udostępnia API).
Krok 4 — odpowiadanie z panelu¶
Z poziomu wątku CS klikasz Odpowiedz → wpisujesz tekst → panel wysyła go do Message Center Allegro przez API. Po sukcesie wiadomość jest natychmiast widoczna w wątku jako oznaczona „My" (niebieskie tło) — patrz FAQ #6.
Allegro automatycznie oznacza wiadomość jako przeczytaną po Twojej odpowiedzi (jedyna platforma z tym wsparciem).
eBay¶
eBay CS jest najszerszy ze wszystkich platform — pobieracz ma cztery niezależne strumienie:
| Strumień | Co pobiera | Częstotliwość |
|---|---|---|
| Messages | Wiadomości z CORE (free-form klient↔sprzedawca) | co 5 min |
| Issues | Aktywne sprawy (cancellations, INR, …) | co 10 min |
| Resolutions | Rozwiązane spory (zamknięte przez eBay) | co 15 min |
| Payment disputes | Spory płatności (chargeback / nieotrzymanie) | co 15 min |
Krok 1 — wymagania konta eBay¶
eBay wymaga, żeby konto miało aktywne Business Policies (Payment / Return / Shipping policies). Bez nich publikacja ofert padnie z błędem Business policies not enabled.
Włączasz w Seller Hub → Account → Business policies → Opt in.
Krok 2 — OAuth¶
Marketplace → Konfiguracja → eBay → Dodaj konto eBay. Otwiera się ekran eBay OAuth, logujesz się, akceptujesz scope-y sell.fulfillment + sell.account + sell.messaging.
Krok 3 — capabilities¶
Po pobraniu sporu / zwrotu pobieracz zapisuje na zgłoszeniu pole capabilities z flagami:
can_accept(czy można zaakceptować spór automatycznie)can_contest(czy można zakwestionować spór)can_add_evidence(czy można dodać dowód)can_decide(dla zwrotów: czy można zdecydować — accept / decline / partial refund)
Te flagi są używane przez węzły eBay dispute action i eBay return decide. Jeśli capabilities.can_X = false, węzeł rzuci UnsupportedSourceError i przebieg trafi do DLQ.
Co eBay udostępnia po API, czego nie¶
✅ Po API (panel obsługuje): - Wiadomości CORE (czytanie + odpowiadanie). - Spory płatności: accept / contest / add evidence. - Zwroty: accept / decline / offer partial refund / provide RMA.
🟠 Tylko deep-link (panel pokazuje link, operator klika): - INR (Item Not Received) inquiries — eBay nie udostępnia API decyzji. - MBG (Money Back Guarantee) cases — jak wyżej.
Amazon¶
Amazon CS jest najbardziej ograniczony — patrz FAQ #20. Aktualnie podpięty jest tylko Amazon.PL; każdy inny rynek wymaga osobnego konta sprzedawcy + osobnej konfiguracji.
Krok 1 — OAuth¶
Marketplace → Konfiguracja → Amazon → Dodaj konto SP-API. Wymaga roli Application Developer w Seller Central (jednorazowy setup po stronie właściciela).
Krok 2 — co Amazon SP-API udostępnia¶
✅ Po API: - Buyer Messages — czytanie wątków klient↔sprzedawca + odpowiadanie przez 9 zamkniętych szablonów. - Returns — odczyt listy zwrotów (refresh co 3h).
❌ Brak API (tylko deep-link do Seller Central): - A-to-z claims — odpowiedź wymaga ręcznego logowania w Seller Central. - Voice of the Customer — brak.
Krok 3 — szablony wiadomości Amazon¶
Amazon nie pozwala na wysyłanie dowolnego tekstu. Każda wiadomość musi być jednym z 9 zamkniętych szablonów:
| Szablon | Kiedy używać |
|---|---|
unexpectedProblem |
Najbliższy „free-form" — wszystko, co nie pasuje do innych. |
confirmOrderDetails |
Potwierdzenie szczegółów zamówienia. |
confirmDeliveryDetails |
Potwierdzenie szczegółów dostawy. |
confirmCustomizationDetails |
Spersonalizowane produkty. |
confirmServiceDetails |
Usługi. |
warranty |
Gwarancja. |
invoice |
Faktura. |
legalDisclosure |
Wymagana informacja prawna. |
digitalAccessKey |
Klucze produktów cyfrowych. |
W węźle Amazon template message wybierasz szablon + dopisujesz właściwą treść w polu text.
Erli¶
Erli to mniejsza polska platforma. Konfiguracja minimalna:
Marketplace → Konfiguracja → Erli → Dodaj konto Erli → OAuth.
Pobieracz: f/marketplace/erli/fetchers/issues co 10 min.
Wspierany strumień: wiadomości (tylko jeden typ — message). Pełna obsługa CRUD wiadomości po stronie API.
Joom¶
Marketplace → Konfiguracja → Joom → OAuth.
Pobieracz tokenów co 50 min. Pobieracz wiadomości w trakcie wdrażania — patrz Listings → Joom.
Moderacja Joom potrafi blokować bez wyjaśnienia
Jeśli zgłoszenia nie wpadają, mimo że wiadomości pojawiają się w panelu sprzedawcy — sprawdź, czy konto nie ma blokady moderacyjnej. Joom nie zawsze zwraca jasny komunikat błędu.
Temu¶
Marketplace → Konfiguracja → Temu → OAuth.
Temu wiąże tokeny z IP serwera
Tokeny Temu są wydane dla konkretnego adresu IP egress (z którego serwer dzwoni). Jeśli infrastruktura zostanie przeniesiona na nowy serwer, wszystkie konta Temu trzeba ponownie podpiąć. To ograniczenie po stronie Temu, nie panelu.
Pobieracz tokenów co 12h. Codzienny scan_expiry sprawdza, czy któreś konto wygasa w ciągu 7 dni i alarmuje przez Forgejo.
WooCommerce (sklepy własne)¶
WooCommerce to Twoje sklepy buyspace.pl (i ewentualne przyszłe sklepy DE / FR). Konfiguracja przez REST API key (nie OAuth).
Krok 1 — wygeneruj klucz API w WooCommerce¶
- W panelu WordPress →
WooCommerce → Settings → Advanced → REST API. - Klikasz „Add key" → opis np. „AIO Factory CS", prawa Read/Write.
- Kopiujesz Consumer key i Consumer secret.
Krok 2 — dodaj sklep w panelu¶
Marketplace → Konfiguracja → WooCommerce → Dodaj sklep → wprowadzasz URL sklepu (https://buyspace.pl) + klucze.
Pobieracz: f/marketplace/woocommerce/fetchers/issues co 10 min — czyta order notes (np. wiadomości od klienta przez formularz kontaktowy z zamówienia).
Polityka read-only¶
Wszystkie pobieracze CS są strict read-only — nie wykonują żadnych zapisów do platformy podczas pobierania:
- Nie oznaczają wiadomości jako przeczytane po stronie platformy.
- Nie zmieniają statusu zgłoszenia / sporu / zwrotu.
- Nie wysyłają potwierdzeń odbioru.
Wszystkie zapisy odbywają się tylko ze scenariuszy (lub ręcznie z poziomu wątku CS — np. odpowiedź operatora). Patrz Głośna szyba bezpieczeństwa.
Wyjątek: węzeł mark_email_read w scenariuszu świadomie flaguje wiadomość Gmail jako przeczytaną — to działanie na żądanie operatora, nie pobieracza. Patrz Reference węzłów → mark_email_read.
Tabela zbiorcza częstotliwości¶
| Źródło | Pobieracz | Częstotliwość |
|---|---|---|
| Email (Gmail) | f/support/imap_fetcher (kontekst Gmail) |
co 5 min |
| Email (Mailcow) | f/support/imap_fetcher (kontekst Mailcow) |
co 5 min |
| Allegro issues | f/marketplace/allegro/fetchers/issues |
co 10 min |
| eBay messages | f/marketplace/ebay/fetchers/messages |
co 5 min |
| eBay issues | f/marketplace/ebay/fetchers/issues |
co 10 min |
| eBay payment disputes | f/marketplace/ebay/fetchers/payment_disputes |
co 15 min |
| eBay resolutions | f/marketplace/ebay/fetchers/resolutions |
co 15 min |
| Amazon returns | f/marketplace/amazon/fetchers/returns |
co 3h |
| Erli issues | f/marketplace/erli/fetchers/issues |
co 10 min |
| WooCommerce issues | f/marketplace/woocommerce/fetchers/issues |
co 10 min |
Token-refresh (osobne crony, niezależne od pobierania zdarzeń):
| Platforma | Częstotliwość | Powód |
|---|---|---|
| Allegro | co 11h | OAuth Allegro wygasa po 12h |
| eBay | co 1h | OAuth eBay wygasa po 2h |
| Amazon | co 50 min | LWA token wygasa po 1h |
| Joom | co 50 min | OAuth wygasa po 1h |
| Temu | co 12h | OAuth wygasa po 24h, ale wymaga re-pinu IP |
Cross-linki¶
- Konfiguracja kont OAuth dla Listings — Listings → przewodnik per platforma. Te same konta = jedno OAuth dla obu modułów.
- Listmonk (mailing masowy) — to inny moduł, nie CS. Patrz Poczta — Listmonk.
- Hasła aplikacji Google — wsparcie Google —
support.google.com/accounts/answer/185833(oficjalna instrukcja). - FAQ #7 — weryfikacja SMTP — #7.
- FAQ #20 — Amazon ograniczenia — #20.
Dane techniczne¶
- UI dodawania kont email:
dashboard/src/routes/marketplace/config/email-accounts/+page.svelte. - Pobieracz IMAP:
f/support/imap_fetcher.pyz dwoma harmonogramami:imap_fetcher_gmail.schedule.yaml+imap_fetcher_mailcow.schedule.yaml. - Marketplace fetcherzy:
f/marketplace/<vendor>/fetchers/*.pyz towarzyszącymi*.schedule.yaml. - Refresh-tokeny:
f/marketplace/<vendor>/refresh_token.pyz osobnym*.schedule.yaml. - Etykiety Gmail (refresh):
f/support/refresh_gmail_labels.py(na żądanie z UI). - Weryfikacja SMTP przed zapisem konta:
f/support/verify_smtp_credentials.py. - Przechowywanie sekretów: hasła kont są szyfrowane po stronie Convex (
cs_email_accounts.imap_password).