1. Czym jest aplikacja

MIOpinie to wtyczka WordPress/WooCommerce napisana na potrzeby jednego sklepu internetowego — marketinstalacji.pl (G7PRO Mariusz Grzanka, ul. Galicyjska 3D/4, 31-586 Kraków). Działa wyłącznie na serwerze tego sklepu.

• Typ: narzędzie wewnętrzne sprzedawcy. Nie jest sprzedawane, udostępniane ani instalowane u innych sprzedawców.
• Użytkownik: jeden — administrator sklepu, który łączy z aplikacją własne konto sprzedawcy na Allegro.
• Środowisko: serwer WWW sklepu (PHP 8, WordPress, WooCommerce). Aplikacja nie ma części działającej w przeglądarce klienta ani aplikacji mobilnej — wszystkie zapytania do Allegro wychodzą z serwera.
• Typ aplikacji w Allegro: OAuth 2.0 Device Flow (aplikacja bez adresu przekierowania).

2. Cel i zakres

Sklep zbiera opinie o obsłudze z dwóch źródeł: od klientów zamówień złożonych w sklepie internetowym oraz od kupujących na Allegro. Aplikacja realizuje trzy cele:

1. Pokazanie ocen z Allegro na stronie sklepu (marketinstalacji.pl/opinie/) obok opinii ze sklepu, z oznaczeniem źródła „Allegro". Klient sklepu widzi, jak sprzedawca jest oceniany na Allegro.
2. Odpowiadanie na oceny z jednego miejsca. Odpowiedź napisana w panelu sklepu jest publikowana pod oceną na Allegro przez API, a dopiero potem pokazywana w sklepie.
3. Utrzymanie zgodności z Allegro. Gdy kupujący zmieni albo usunie ocenę na Allegro, zmiana jest odwzorowywana w sklepie — nie pokazujemy ocen, których na Allegro już nie ma.

Czego aplikacja nie robi: nie odczytuje ani nie zmienia ofert, cen, stanów magazynowych, zamówień, płatności, wiadomości ani danych kupujących. Nie pobiera danych innych sprzedawców, nie przeszukuje katalogu Allegro i nie prezentuje ofert z Allegro w żadnym innym serwisie.

3. Jak działa

Administrator sklepu ──(1) łączy konto, Device Flow──▶ allegro.pl/auth/oauth
                                                        │ token dostępu + odświeżający
Serwer sklepu (WordPress + MIOpinie) ◀──────────────────┘
   │
   ├─(2) co 6 h:   GET /sale/user-ratings?lastChangedAt.gte=…   (nowe i zmienione oceny)
   ├─(3) raz/dobę: GET /sale/user-ratings  (pełna lista → usunięcie ocen skasowanych na Allegro)
   ├─(4) na żądanie administratora: PUT /sale/user-ratings/{id}/answer  (odpowiedź sklepu)
   │
   └──▶ baza danych sklepu ──▶ strona /opinie/ (oceny z etykietą „Allegro")

1. Połączenie konta. Administrator w panelu WordPress (WooCommerce → Opinie → Allegro) wpisuje Client ID i Client Secret aplikacji zarejestrowanej na swoim koncie, klika „Połącz", potwierdza dostęp na stronie Allegro i wraca do panelu. Szczegóły w sekcji 4.
2. Pierwszy import. Zaraz po połączeniu aplikacja pobiera w tle pełną listę ocen sprzedawcy (strony po 100 ocen).
3. Synchronizacja przyrostowa co 6 godzin. Pobierane są tylko oceny zmienione od ostatniego udanego przebiegu (filtr lastChangedAt.gte, z godziną zapasu). Zmieniona ocena nadpisuje poprzednią wersję — bez duplikatów.
4. Pełne uzgodnienie raz na dobę. Aplikacja pobiera całą listę ocen i usuwa ze sklepu te, których na Allegro już nie ma. Usuwanie następuje wyłącznie po pobraniu kompletnej listy — przerwane połączenie nie spowoduje skasowania prawdziwych ocen.
5. Odpowiedzi. Gdy administrator odpowiada na ocenę z Allegro, aplikacja wysyła odpowiedź na Allegro (do 500 znaków). Dopiero po potwierdzeniu przez Allegro odpowiedź pojawia się w sklepie. Odpowiedzi napisane bezpośrednio na Allegro są pobierane przy synchronizacji.
6. Wyświetlanie. Strona /opinie/ pokazuje oceny z etykietą źródła „Allegro" i informacją, że pochodzą z Allegro i są tam aktualizowane.

Zadania cykliczne uruchamia Action Scheduler (kolejka zadań WooCommerce) — tylko wtedy, gdy konto jest połączone.

4. Autoryzacja użytkownika

Aplikacja korzysta wyłącznie z mechanizmu autoryzacji Allegro — OAuth 2.0 Device Flow. Nie ma własnego mechanizmu logowania do Allegro, nigdy nie prosi o login ani hasło do Allegro i nigdzie ich nie zapisuje.

1. Aplikacja wysyła POST https://allegro.pl/auth/oauth/device (uwierzytelnienie Basic: Client ID i Client Secret) z zakresami allegro:api:ratings allegro:api:profile:read.
2. Allegro zwraca device_code, user_code i adres weryfikacji. Panel pokazuje kod i przycisk „Otwórz Allegro i zatwierdź".
3. Administrator loguje się na Allegro (po stronie Allegro, z uwierzytelnianiem dwuskładnikowym) i zatwierdza dostęp.
4. Po kliknięciu „Zakończ łączenie" aplikacja wysyła POST https://allegro.pl/auth/oauth/token z grant_type=urn:ietf:params:oauth:grant-type:device_code. Odpowiedź authorization_pending lub slow_down jest pokazywana administratorowi jako „jeszcze nie zatwierdzono" — aplikacja nie odpytuje Allegro w pętli.
5. Po otrzymaniu tokenów aplikacja wykonuje GET /me, żeby pokazać w panelu, z którym kontem nastąpiło połączenie.

Tokeny

• Token dostępu (ważny 12 h) jest odświeżany 5 minut przed wygaśnięciem przez grant_type=refresh_token. Nowy token odświeżający zastępuje poprzedni.
• Odświeżanie jest chronione blokadą, więc dwa równoległe procesy nie wymienią tokenu jednocześnie.
• Po odpowiedzi 401 aplikacja odświeża token i ponawia zapytanie jeden raz.
• Gdy Allegro unieważni dostęp (invalid_grant — np. odebranie uprawnień lub zmiana hasła), aplikacja kasuje tokeny, wstrzymuje synchronizację i prosi administratora o ponowne połączenie. Nie ponawia zapytań w nieskończoność.
• Administrator może w każdej chwili kliknąć „Rozłącz konto" — tokeny są kasowane, a zadania cykliczne usuwane. Dostęp można też odebrać po stronie Allegro.

Zakresy uprawnień (minimalne)

Aplikacja nie prosi o dostęp do ofert, zamówień, płatności, wiadomości ani ustawień konta.

5. Wykorzystywane zasoby API

Zapytania do REST API używają nagłówków Accept: application/vnd.allegro.public.v1+json i Authorization: Bearer …. Identyfikator oceny jest sprawdzany wzorcem [A-Za-z0-9-] przed wstawieniem do adresu. Aplikacja łączy się wyłącznie z adresami allegro.pl i api.allegro.pl (w trybie testowym: allegrosandbox.pl).

6. Liczba i częstotliwość zapytań

Ruch jest bardzo mały i przewidywalny:

• synchronizacja przyrostowa: 4 przebiegi na dobę, zwykle po 1 zapytaniu;
• pełne uzgodnienie: 1 przebieg na dobę, 1 zapytanie na każde 100 ocen;
• odświeżenie tokenu: ok. 2 zapytania na dobę;
• odpowiedzi: pojedyncze zapytania wywołane ręcznie przez administratora.

Przy kilkuset ocenach to około 10–15 zapytań na dobę. Każde zapytanie ma limit czasu 20 s. Błąd synchronizacji nie powoduje natychmiastowych ponowień — kolejna próba następuje w następnym zaplanowanym przebiegu, od tego samego miejsca. Pobieranie stron kończy się przy przesunięciu 20 000, zgodnie z limitem zasobu.

7. Identyfikacja aplikacji (User-Agent)

Każde zapytanie — do REST API i do serwera autoryzacji — zawiera nagłówek:

User-Agent: MIOpinie/0.2.1 (+https://marketinstalacji.pl/mi-opinie-allegro/)

MIOpinie to nazwa aplikacji zarejestrowanej w Allegro Developer Apps, 0.2.1 to bieżąca wersja produkcyjna, a adres prowadzi do tej strony.

8. Dane: co zapisujemy i co pokazujemy

• Aplikacja nie pobiera ani nie przetwarza adresów e-mail, imion, nazwisk, adresów ani numerów telefonów kupujących.
• Na stronie sklepu pokazujemy wyłącznie oceny tego sprzedawcy, w formie, w jakiej są publicznie dostępne na jego profilu na Allegro, z etykietą źródła „Allegro". Nie pokazujemy ofert, cen ani statystyk sprzedaży.
• Oceny usunięte na Allegro są usuwane ze sklepu przy najbliższym pełnym uzgodnieniu (najpóźniej po dobie).
• Dane nie są przekazywane osobom trzecim ani wykorzystywane do marketingu. Przetwarzanie opisuje polityka prywatności sklepu.

9. Bezpieczeństwo

• Client Secret i tokeny są szyfrowane w bazie danych (libsodium crypto_secretbox, klucz wyprowadzony z kluczy bezpieczeństwa WordPressa). Zalecana konfiguracja przechowuje Client ID i Client Secret w pliku wp-config.php poza bazą.
• Sekret nigdy nie jest wyświetlany w panelu ani zapisywany w logach. Tokeny nie trafiają do przeglądarki — wszystkie zapytania wychodzą z serwera.
• Dostęp do ustawień i do łączenia konta ma tylko administrator sklepu; formularze są chronione tokenami CSRF WordPressa (nonce).
• Połączenia wyłącznie do stałych adresów Allegro przez HTTPS — adres docelowy nie zależy od danych wejściowych.
• Dane z API są oczyszczane przed zapisem i escapowane przy wyświetlaniu (ochrona przed XSS).
• Odinstalowanie wtyczki kasuje Client Secret, tokeny i stan synchronizacji.
• Klucz aplikacji (Client ID / Secret) jest używany tylko przez tę jedną instalację i nie jest nikomu udostępniany.

10. Zgodność z Regulaminem REST API Allegro

11. Kontakt

W sprawach związanych z aplikacją i jej ruchem do Allegro:
G7PRO Mariusz Grzanka, ul. Galicyjska 3D/4, 31-586 Kraków
e-mail: sklep@marketinstalacji.pl