MARKET-TOOLS SYNC

Dokumentacja aplikacji wykorzystującej Allegro REST API

Rodzaj: prywatna aplikacja do użytku wewnętrznego
Operator: MONTERA GRUPA SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ
Obsługiwane konta Allegro: market-tools_pl oraz market-tools
Status: rozwój, testy i przygotowanie do produkcji
Kontakt: montera@vp.pl

1. Przeznaczenie i cel aplikacji

MARKET-TOOLS SYNC jest niezależnym systemem służącym do centralnego zarządzania stanami magazynowymi, cenami i dostępnością ofert na dwóch własnych kontach sprzedawcy Allegro.

Aplikacja ma trzy główne zadania: synchronizację stanów magazynowych między kontami, ustalanie i aktualizowanie cen ofert oraz automatyczne wznawianie ofert po uzupełnieniu magazynu.

System powstaje na potrzeby własnej działalności handlowej. Nie jest usługą SaaS ani aplikacją udostępnianą innym sprzedawcom.

2. Centralna baza produktów i identyfikacja ofert

Podstawą działania jest wspólna baza produktów magazynowych. Głównym identyfikatorem produktu jest SKU (sygnatura).

Jeden produkt magazynowy może być powiązany z wieloma ofertami na różnych kontach Allegro. Oferty mogą mieć różne identyfikatory, nazwy lub kody EAN, ale wykorzystywać jeden wspólny stan magazynowy.

Przed synchronizacją system kontroluje powiązanie produktu z ofertą oraz zgodność danych identyfikacyjnych.

Baza przechowuje informacje o produktach, ofertach, stanach fizycznych, rezerwacjach, cenach i wynikach synchronizacji.

3. Synchronizacja stanów magazynowych

3.1. Zasada działania

MARKET-TOOLS SYNC utrzymuje wspólny stan magazynowy produktów wystawionych na dwóch kontach Allegro.

Stan dostępny do sprzedaży jest obliczany na podstawie stanu fizycznego pomniejszonego o istniejące rezerwacje.

System porównuje dane magazynowe z ilościami na powiązanych ofertach i przygotowuje odpowiednie aktualizacje.

3.2. Przykład synchronizacji

Produkt SKU ABC-001 ma 10 dostępnych sztuk i jest wystawiony na obu kontach Allegro. Obie oferty wskazują 10 sztuk.

Po sprzedaży jednej sztuki na pierwszym koncie i uwzględnieniu zamówienia we wspólnym magazynie dostępność spada do 9 sztuk. System powinien zsynchronizować obie oferty do ilości 9 sztuk.

Nie są to dwa oddzielne magazyny po 10 sztuk, lecz jedna pula towaru dostępna na dwóch kontach.

3.3. Zamówienia i rezerwacje

Aplikacja odczytuje zamówienia i ich statusy za pomocą Allegro REST API wyłącznie w zakresie potrzebnym do obliczania dostępności towarów i rezerwacji magazynowych.

Uwzględniane są zdarzenia wpływające na dostępność produktów, w tym sprzedaż i anulowania zamówień.

System nie wykorzystuje tych danych do księgowości ani generowania przesyłek.

3.4. Uzupełnianie i aktualizacja stanów magazynowych

MARKET-TOOLS SYNC umożliwia aktualizowanie stanów produktów we wspólnej bazie magazynowej.

Zmiana może wynikać z przyjęcia dostawy, ponownego wprowadzenia zwróconego produktu do sprzedaży albo ręcznej korekty ilości.

Po zarejestrowaniu zmiany system przelicza dostępny stan, uwzględnia rezerwacje i synchronizuje właściwe ilości na ofertach obu kont Allegro, po spełnieniu wymaganych warunków.

Aplikacja nie służy do automatycznego zamawiania towarów u dostawców ani do obsługi całego procesu zwrotów.

3.5. Kontrola synchronizacji

Przed wysłaniem zmiany system sprawdza powiązanie oferty, stan produktu, rezerwacje i status poprzednich operacji.

W przypadku niezgodności danych albo nierozstrzygniętej operacji zmiana może zostać wstrzymana do czasu jej wyjaśnienia.

4. Zarządzanie cenami ofert

MARKET-TOOLS SYNC pozwala odczytywać i ustalać ceny konkretnych ofert Allegro oraz przygotowywać ich aktualizacje przez REST API.

Operator wybiera produkt lub ofertę.
System identyfikuje właściwe konto i ofertę Allegro.
Operator ustala nową cenę.
Mechanizm aktualizacji przesyła zmianę przy użyciu OAuth.
Wynik operacji podlega weryfikacji.

Oferty powiązane z jednym produktem nie muszą mieć jednakowej ceny. Aplikacja nie służy do automatycznego śledzenia cen konkurencji.

5. Automatyczne wznawianie zakończonych ofert

5.1. Warunki wznowienia

Mechanizm wznowień jest przeznaczony dla ofert zakończonych wskutek wyczerpania stanu magazynowego.

Przed wznowieniem sprawdzana jest tożsamość oferty i konta, SKU, status i przyczyna zakończenia, dostępny stan, rezerwacje, aktualność zamówień oraz status wcześniejszych operacji.

5.2. Kolejność działania

Wykrycie oferty zakończonej z powodu braku towaru.
Stwierdzenie ponownej dostępności produktu.
Sprawdzenie danych magazynu oraz powiązań obu kont.
Zarejestrowanie zamiaru przywrócenia stanu.
Aktualizacja ilości na odpowiedniej ofercie.
Weryfikacja rzeczywistego stanu po zmianie.
Wysłanie żądania wznowienia oferty.
Sprawdzenie statusu oferty w Allegro.
Potwierdzenie aktywacji po pozytywnej weryfikacji.

Niepewny wynik operacji nie powinien powodować automatycznego ponowienia identycznego żądania bez sprawdzenia stanu oferty.

5.3. Ograniczenia

System nie jest przeznaczony do automatycznego wznawiania każdej zakończonej oferty, niezależnie od przyczyny zakończenia. Wznowienie wymaga spełnienia odpowiednich warunków bezpieczeństwa.

6. Architektura techniczna

Aplikacja działa na prywatnym serwerze VPS. Wykorzystuje Python, PostgreSQL i kontenery Docker.

Architektura obejmuje panel operacyjny, centralną bazę produktów, mechanizmy synchronizacji oraz komunikację z Allegro REST API.

Dokumentacja jest udostępniona przez HTTPS niezależnie od panelu operacyjnego. Baza danych nie jest publiczną częścią dokumentacji.

7. Połączenie z Allegro i autoryzacja

7.1. OAuth 2.0

MARKET-TOOLS SYNC wykorzystuje OAuth 2.0 Authorization Code z mechanizmem PKCE.

Operator rozpoczyna połączenie konta w aplikacji.
Zostaje przekierowany do strony autoryzacji Allegro.
Loguje się bezpośrednio w Allegro i zatwierdza uprawnienia.
Aplikacja odbiera kod autoryzacyjny.
Kod jest wymieniany na tokeny OAuth po stronie serwera.
Tokeny są wykorzystywane w granicach przyznanych uprawnień.

Aplikacja nie wymaga podawania haseł do kont Allegro.

7.2. Obsługa dwóch kont

Docelowo jeden klucz aplikacji MARKET-TOOLS SYNC będzie wykorzystywany do indywidualnej autoryzacji dwóch własnych kont sprzedawcy: market-tools_pl i market-tools.

Każda operacja API jest przyporządkowywana do właściwego konta i identyfikatora oferty.

7.3. Zabezpieczenia kont

Na obu kontach Allegro operator stosuje uwierzytelnianie dwuskładnikowe (2FA) z użyciem Google Authenticator.

8. Zasoby REST API i uprawnienia

Docelowa integracja wymaga następujących zakresów OAuth:

Scope	Cel
`allegro:api:profile:read`	Identyfikacja podłączonego konta.
`allegro:api:sale:offers:read`	Odczyt ofert, cen, stanów, statusów i identyfikatorów.
`allegro:api:sale:offers:write`	Aktualizacja cen i stanów oraz wznawianie ofert.
`allegro:api:orders:read`	Odczyt zamówień do rozliczania magazynu i rezerwacji.

MARKET-TOOLS SYNC nie wymaga uprawnień do generowania przesyłek ani prowadzenia księgowości.

9. Dostęp i bezpieczeństwo

9.1. Kontrola dostępu

MARKET-TOOLS SYNC jest prywatnym systemem operatora. Nie oferuje samodzielnej rejestracji zewnętrznych sprzedawców. Publiczna dokumentacja nie udostępnia funkcji zarządzania ofertami.

9.2. Tokeny i dane poufne

Tokeny OAuth oraz dane uwierzytelniające są obsługiwane po stronie serwera. Implementacja zawiera szyfrowanie przechowywanych tokenów i rozdzielenie konfiguracji poufnej od publicznej dokumentacji.

Client Secret, tokeny, klucze szyfrujące i hasła do bazy nie są publikowane w dokumentacji.

9.3. Kontrola zmian

Przed operacją modyfikującą system sprawdza wymagane warunki, w tym zgodność produktu i oferty, stan magazynu, rezerwacje oraz status wcześniejszych operacji.

Mechanizmy aktualizacji stanów i wznowień przewidują zapis zamiaru operacji przed wysłaniem żądania API oraz późniejszą weryfikację rzeczywistego wyniku.

9.4. Obsługa niepewnych wyników

Zerwanie połączenia albo niejednoznaczna odpowiedź nie są traktowane jako potwierdzenie wykonania operacji. Projekt przewiduje blokowanie automatycznych ponowień takich żądań do czasu sprawdzenia ich rzeczywistego skutku.

9.5. Baza danych i kopie zapasowe

PostgreSQL przechowuje dane produktów, magazynu, powiązania ofert, rezerwacje i informacje o synchronizacji. Na VPS skonfigurowano cykliczne kopie zapasowe, kontrole ich poprawności i powiadomienia o wykrytych błędach.

9.6. Oddzielenie środowisk

Podczas rozwoju wykorzystano środowisko Allegro Sandbox. Integracja produkcyjna ma osobną konfigurację, konta i zabezpieczenia operacji zapisu. Zapisy na rzeczywistych kontach są obecnie wyłączone.

Pełne działanie zabezpieczeń produkcyjnych wymaga zakończenia integracji i testów po uzyskaniu odpowiedniego dostępu API.

10. Aktualny status aplikacji i plan uruchomienia

MARKET-TOOLS SYNC znajduje się w fazie rozwoju i testów. Nie jest jeszcze ukończonym systemem produkcyjnym.

Elementy przygotowane i testowane

Środowisko VPS, Docker i PostgreSQL.
Panel aplikacji i baza produktów magazynowych.
Powiązania produktów z ofertami Allegro.
Testy synchronizacji stanów i cen w Sandbox.
Testy wybranych scenariuszy wznowień ofert.
Izolowane testy mechanizmów produkcyjnych.
Mechanizmy wykonywania i kontroli kopii zapasowych.

Elementy do zakończenia

Uzyskanie osobnego klucza REST API dla MARKET-TOOLS SYNC.
Podłączenie dwóch istniejących kont Allegro (market-tools_pl i market-tools) za pomocą OAuth 2.0 po uzyskaniu klucza.
Dokończenie integracji modułów w jednym systemie.
Kontrolowane testy synchronizacji stanów i cen na produkcji.
Kontrolowane testy automatycznego wznawiania ofert.
Uruchomienie docelowych automatycznych cykli produkcyjnych.

11. Odrębność od iBiznesmontera

iBiznesmontera jest istniejącą, działającą aplikacją do księgowości, dokumentowania sprzedaży i generowania przesyłek.

Nie synchronizuje stanów magazynowych między kontami, nie zarządza cenami ofert i nie wznawia zakończonych ofert.

MARKET-TOOLS SYNC jest odrębnym systemem do synchronizacji magazynu, zarządzania cenami i wznowień.

Oba programy mogą odczytywać informacje o zamówieniach, ale wykorzystują je do różnych celów: iBiznesmontera do obsługi sprzedaży, a MARKET-TOOLS SYNC do rozliczania magazynu i rezerwacji.

12. Uzasadnienie osobnego klucza REST API

Istniejący klucz REST API jest wykorzystywany przez działający system iBiznesmontera.

MARKET-TOOLS SYNC nie jest jego kopią ani drugą instancją. Posiada własną logikę, kod, bazę danych i konfigurację.

Oddzielny klucz pozwoli jednoznacznie identyfikować żądania obu integracji, niezależnie zarządzać ich dostępem, rozdzielić operacje magazynowe od księgowych i wysyłkowych oraz rozwijać systemy bez zakłócania ich działania.

Operator wnioskuje o dodatkowy klucz dla odrębnej aplikacji, zgodnie z procedurą indywidualnego rozpatrywania takich wniosków.

13. Identyfikacja aplikacji

Docelowy nagłówek User-Agent zawiera nazwę aplikacji, jej wersję i adres publicznej dokumentacji:

MARKET-TOOLS-SYNC/1.0 (+https://vps16674.awhost.cloud/)

Wartość została przygotowana w konfiguracji produkcyjnej; zostanie zastosowana w działającej aplikacji podczas wdrożenia.

14. Dane kontaktowe

MARKET-TOOLS SYNC
Operator: MONTERA GRUPA SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ
Obsługiwane konta Allegro: market-tools_pl oraz market-tools
Dokumentacja: https://vps16674.awhost.cloud/
Kontakt: montera@vp.pl

Dokumentacja opisuje aktualny stan i docelowe działanie aplikacji. Będzie aktualizowana wraz z zakończeniem testów produkcyjnych.