Dokumentacja techniczna

Ten dokument opisuje w jaki sposób Healsy integruje się z API Allegro — jakie uprawnienia OAuth pobieramy, jakie dane przechowujemy, jak je zabezpieczamy oraz do kogo pisać w sprawach technicznych. Dokument służy jako oficjalna dokumentacja integracji zgłaszana do Allegro Developer Portal.

1. O aplikacji Healsy

Healsy to narzędzie SaaS dla sprzedawców Allegro, które automatyzuje audyt kondycji konta, generuje treści ofert (tytuły, opisy, parametry) z użyciem AI oraz proponuje rekomendacje optymalizacyjne. Każda zmiana danych na koncie Allegro klienta wymaga jego jawnego zatwierdzenia (human-in-the-loop) i jest logowana w wewnętrznym rejestrze zmian z możliwością wycofania.

Aplikacja jest przeznaczona dla polskich sprzedawców Allegro w segmencie 50–5000 aktywnych ofert oraz agencji obsługujących takich klientów. Produkt jest w fazie przygotowania do komercyjnego uruchomienia (planowany Q3 2026).

2. Zakres integracji z API Allegro (OAuth scopes)

Integracja odbywa się przez oficjalne OAuth 2.0 (przepływ Authorization Code) — użytkownik wyraża zgodę na dostęp w panelu Allegro i w każdej chwili może odłączyć integrację. Uzyskujemy dokładnie te uprawnienia, których wymaga każda udostępniona funkcja aplikacji:

• allegro:api:sale:offers:read — odczyt aktywnych i zakończonych ofert użytkownika w celu audytu ich jakości (tytuły, opisy, parametry, zdjęcia, statystyki widoczności).
• allegro:api:sale:offers:write — publikacja nowych ofert oraz modyfikacja istniejących (aktualizacja tytułu, opisu, ceny, parametrów). Każda operacja zapisu wymaga jawnego zatwierdzenia przez użytkownika w interfejsie aplikacji.
• allegro:api:sale:settings:read oraz allegro:api:sale:settings:write — odczyt i zapis ustawień sprzedaży (cenniki dostaw, osoby odpowiedzialne, dane producenta wymagane przez GPSR).
• allegro:api:orders:read — odczyt zamówień w celu generowania raportów finansowych, obliczania marży i statystyk sprzedaży.
• allegro:api:billing:read — odczyt opłat Allegro (prowizja, Ads, wysyłka, wyróżnienia) w celu odtworzenia rzeczywistego wyniku finansowego 1:1 z Panelem Allegro.
• allegro:api:profile:read — odczyt podstawowych danych profilu sprzedawcy (login, identyfikator) w celu identyfikacji konta w aplikacji.
• allegro:api:messaging — odczyt i odpowiadanie na wiadomości od kupujących (moduł obsługi klienta z asystentem AI).
• allegro:api:disputes — obsługa dyskusji i sporów z kupującymi.

Aplikacja nigdy nie prosi o hasło do konta Allegro — cały przepływ autoryzacji odbywa się w domenie Allegro. Tokeny dostępowe (access token, refresh token) otrzymujemy bezpośrednio od Allegro i przechowujemy w formie zaszyfrowanej po naszej stronie.

3. Jakie dane przechowujemy

W celu realizacji funkcji audytu, historii zmian oraz generowania raportów przechowujemy w naszej bazie danych następujące kategorie informacji pochodzące z API Allegro:

• Dane ofert (tytuł, opis, kategoria, parametry, zdjęcia, cena, stan magazynowy, statystyki wyświetleń i konwersji).
• Dane zamówień (numer, status, kwota, koszty wysyłki, dane dostawy — bez danych osobowych kupującego wykraczających poza to co niezbędne).
• Rozliczenia (prowizje, opłaty za usługi dodatkowe, wpływy).
• Tokeny OAuth (zaszyfrowane algorytmem AES-256 / Fernet).
• Log wszystkich zmian dokonanych przez aplikację w koncie użytkownika.

Dane są przechowywane w lokalnej bazie PostgreSQL na infrastrukturze na terenie Unii Europejskiej i nie są udostępniane podmiotom trzecim poza dostawcami infrastruktury opisanymi w Polityce prywatności.

4. Bezpieczeństwo

• Cała komunikacja z API Allegro oraz z użytkownikiem odbywa się wyłącznie przez HTTPS (TLS 1.2+).
• Tokeny OAuth Allegro przechowujemy w bazie zaszyfrowane symetrycznie (klucz szyfrujący trzymany osobno od bazy danych).
• Hasła użytkowników do Healsy są hashowane algorytmem Argon2id — nigdy nie przechowujemy haseł ani do Healsy, ani do Allegro w formie odwracalnej.
• Sesje w przeglądarce oparte na cookies HttpOnly z ochroną CSRF (double-submit token). Frontend aplikacji nie trzyma tokenów w localStorage.
• Izolacja danych między klientami zapewniona trójwarstwowo: filtrem client_id na poziomie każdego zapytania SQL, wzorcem programistycznym z weryfikacją w CI oraz Row-Level Security po stronie PostgreSQL.
• Klucze API do Healsy dla integratorów są hashowane algorytmem SHA-256.
• Dane kart płatniczych nie są przechowywane — cała obsługa płatności odbywa się przez zewnętrznego operatora (PayNow) w modelu hosted checkout.

5. Odwracalność zmian

Każda operacja modyfikująca dane na koncie Allegro użytkownika (edycja oferty, zmiana ceny, zmiana budżetu kampanii Ads, publikacja) jest zapisywana w wewnętrznym rejestrze zmian z pełnym stanem przed i po. Użytkownik może cofnąć każdą taką zmianę w interfejsie aplikacji jednym kliknięciem — Healsy wykona operację odwrotną przez to samo API Allegro.

Domyślnie wszystkie rekomendacje generowane przez naszą warstwę AI wymagają jawnej akceptacji użytkownika przed wykonaniem (tzw. human-in-the-loop). Nie stosujemy trybu autopilota dla mutacji na koncie użytkownika.

6. Odłączenie integracji

Użytkownik może w każdej chwili odłączyć integrację z Allegro w panelu Healsy (Ustawienia → Konto Allegro) lub bezpośrednio w panelu Allegro (Ustawienia konta → Zezwolenia). W obu przypadkach nasze tokeny są natychmiast unieważniane i przestają działać.

Historyczne dane pobrane przed odłączeniem integracji (cache ofert, historia zamówień) są usuwane w ciągu 30 dni od odłączenia. Użytkownik może zażądać natychmiastowego usunięcia wszystkich danych zgodnie z prawem do bycia zapomnianym (RODO art. 17) — patrz Polityka prywatności.

7. Zgodność z regulaminem Allegro

Wszystkie treści generowane przez warstwę AI (tytuły, opisy, parametry) przed publikacją przechodzą przez wewnętrzny walidator regulaminowy, który blokuje publikację treści niezgodnych z Regulaminem Allegro (m.in. słowa zakazane, znaki zastrzeżone, elementy magnesujące typu „HIT”, „PROMOCJA” w tytułach). Aplikacja monitoruje zmiany w Regulaminie Allegro i aktualizuje reguły walidatora na bieżąco.

8. Podmiot odpowiedzialny i kontakt

Podmiotem odpowiedzialnym za rozwój i utrzymanie aplikacji Healsy jest:

W sprawach technicznych dotyczących integracji z Allegro, zgłoszeń błędów lub pytań o bezpieczeństwo prosimy o kontakt na powyższy email.

Odpowiadamy w ciągu 2 dni roboczych. W sprawach bezpieczeństwa (zgłoszenie podatności) odpowiadamy w ciągu 24 godzin.

9. Ochrona danych osobowych

Sposób przetwarzania danych osobowych, prawa użytkownika (dostęp, sprostowanie, usunięcie, przenoszenie, wycofanie zgody) oraz szczegóły dotyczące podwykonawców przetwarzania danych opisane są w naszej Polityce prywatności.

10. Zmiany w dokumentacji

Niniejsza dokumentacja techniczna może być aktualizowana w miarę rozwoju integracji z Allegro (dodawanie nowych funkcji, rozszerzanie zakresu uprawnień OAuth, zmiany w architekturze bezpieczeństwa). O istotnych zmianach zakresu integracji informujemy wcześniej użytkowników przez email oraz w panelu aplikacji.