Dokumentacja Spinacza

1. Cel aplikacji

Spinacz udostępnia sprzedawcy dane jego własnego konta Allegro w asystentach AI (Claude, Claude Code, ChatGPT) przez protokół MCP. Sprzedawca pyta o sprzedaż, opłaty i zysk na ofertach oraz zmienia ceny i stany ofert po potwierdzeniu podglądu. Usługa służy sprzedawcom, którzy sami podłączają swoje konta; Spinacz nie prezentuje danych innych sprzedawców ani ofert Allegro w innych serwisach.

2. Funkcje

Działające: lista połączonych kont, przegląd konta (jakość sprzedaży, oferty według statusu, zamówienia do wysłania), wyszukiwanie ofert ze statystykami, szczegóły oferty, lista zamówień, raport sprzedaży, raport opłat z historii rozliczeń, zysk na ofertach (przychód minus opłaty Allegro minus koszt zakupu podany przez sprzedawcę), kalkulator opłat dla wskazanych cen, podgląd i zatwierdzenie zmian cen i stanów, historia zmian i ich cofanie.

Planowane: połączenie z danymi Base (BaseLinker), Shopera i Amazona w jednej rozmowie.

3. Autoryzacja

Sprzedawca zakłada konto w Spinaczu (logowanie linkiem e-mail), a następnie łączy konto Allegro przez OAuth 2.0 (authorization code z PKCE). Logowanie odbywa się wyłącznie na stronie Allegro; Spinacz nie poznaje hasła. Client ID i Client Secret aplikacji pozostają na serwerze Spinacza; sprzedawca nie generuje ani nie przekazuje kluczy. Token dostępu jest odświeżany na serwerze. Klienci AI łączą się ze Spinaczem przez osobny OAuth 2.1 Spinacza (MCP) i nigdy nie otrzymują tokenów Allegro.

4. Zakres uprawnień

Scope	Dane	Funkcja
`allegro:api:profile:read`	Identyfikator i login konta, wynik jakości sprzedaży	Przegląd konta, rozpoznanie połączonego konta
`allegro:api:sale:offers:read`	Oferty: tytuł, cena, stan, sprzedane sztuki, wyświetlenia, obserwujący, parametry; kalkulator opłat	Wyszukiwanie ofert, szczegóły oferty, kalkulator opłat, podgląd zmian
`allegro:api:sale:offers:write`	Cena i stan wskazanych ofert	Zmiana cen i stanów po potwierdzeniu podglądu przez sprzedawcę; cofnięcie zmiany
`allegro:api:orders:read`	Zamówienia: pozycje, kwoty, statusy, metoda dostawy, przypisanie do Allegro Ads	Lista zamówień i raport sprzedaży; dane osobowe kupujących są odrzucane i nie trafiają do AI
`allegro:api:billing:read`	Historia rozliczeń: opłaty i prowizje	Raport opłat i zysk na ofertach

5. Bezpieczeństwo i rozdzielenie danych

Tokeny Allegro są szyfrowane w bazie (AES, klucz poza bazą) i nie opuszczają serwera.
Każde zapytanie do danych jest wiązane z kontem Spinacza i połączonym kontem Allegro; użytkownik widzi wyłącznie swoje konta.
Zmiany na Allegro wymagają podglądu i osobnego potwierdzenia; każda zmiana trafia do historii z wartością sprzed zmiany.
Odłączenie konta usuwa tokeny; sprzedawca może też odłączyć aplikację w „Powiązanych aplikacjach” w Allegro.
Każde zapytanie do Allegro ma nagłówek User-Agent: Spinacz/0.1.0 (+https://spinacz.syntropicsignal.ai).

6. Status

Usługa działa produkcyjnie. Wersja 0.1.0.

7. Dostęp testowy

Adres serwera MCP: https://spinacz.syntropicsignal.ai/mcp. Dostęp do konta testowego dla weryfikacji przekażemy na prośbę wysłaną na hello@syntropicsignal.ai.

8. Scenariusze weryfikacji

Załóż konto Spinacza i połącz konto Allegro: logowanie na stronie Allegro, powrót na stronę konta.
W Claude Code: claude mcp add --transport http spinacz https://spinacz.syntropicsignal.ai/mcp, następnie /mcp i zgoda.
Zapytaj: „Pokaż przegląd mojego konta Allegro” i „Ile zarobiłem w ostatnich 7 dniach po opłatach?”.
Poproś o zmianę ceny jednej oferty: asystent pokazuje podgląd, a zmiana następuje dopiero po potwierdzeniu.
Cofnij zmianę z historii.

9. Wymagania

Konto sprzedawcy Allegro z co najmniej jedną ofertą; asystent obsługujący zdalne serwery MCP z OAuth (Claude, Claude Code, ChatGPT w trybie dewelopera).

10. Kontakt

VECTORLENS spółka z ograniczoną odpowiedzialnością z siedzibą w Dębicy, ul. Rzeszowska 66/2, 39-200 Dębica, KRS 0001190119, NIP 8722455725, REGON 542524203, działająca pod marką Syntropic. E-mail: hello@syntropicsignal.ai.