AllegroSync – obsługa zamówień Allegro

1. O aplikacji

AllegroSync automatycznie przyjmuje opłacone zamówienia z Allegro do systemu ERP firmy (Comarch ERP Optima) jako dokumenty rezerwacji odbiorcy. Na ich podstawie magazyn kompletuje i nadaje paczki. Aplikacja zastępuje ręczne przepisywanie zamówień przez pracownika, co skraca czas realizacji i eliminuje pomyłki.

Po przyjęciu zamówienia do systemu ERP aplikacja ustawia na Allegro status realizacji „W realizacji”, dzięki czemu kupujący od razu widzi, że zamówienie zostało przyjęte.

Producent i jedyny użytkownik: MARINOX Sp. z o.o. (marinox.pl). Aplikacja jest wewnętrznym narzędziem firmy: nie jest sprzedawana ani udostępniana innym sprzedającym i obsługuje wyłącznie konto sprzedawcy MARINOX na Allegro.

2. Różnica względem aplikacji AllegroManager

Obie aplikacje należą do pakietu narzędzi firmy MARINOX Nexus, ale obsługują rozłączne obszary API i działają w innym miejscu oraz w innym trybie.

	AllegroManager	AllegroSync (ta aplikacja)
Obszar	oferty: tworzenie, edycja, ceny, stany, publikacja	zamówienia: przyjęcie do ERP i status realizacji
Kto używa	pracownicy działu sprzedaży, ręcznie	nikt ręcznie – usługa działająca samodzielnie
Gdzie działa	komputery stanowisk sprzedaży	jeden serwer aplikacyjny firmy, całą dobę
Zasoby API	`/sale/*` – oferty i ich parametry	`/order/` – zamówienia, bez dostępu do ofert*
Dane kupujących	nie przetwarza	przetwarza w zakresie potrzebnym do realizacji zamówienia

Osobna rejestracja rozdziela uprawnienia: automat na serwerze nie ma prawa do zmiany ofert, a program do zarządzania ofertami nie ma dostępu do danych kupujących. Każda aplikacja ma własne tokeny, więc unieważnienie jednej nie zatrzymuje drugiej, a ruch każdej z nich jest osobno widoczny po stronie Allegro.

3. Jak działa aplikacja

Dziennik zdarzeń. Co 2 minuty aplikacja pobiera nowe zdarzenia z GET /order/events, zaczynając od ostatnio przetworzonego zdarzenia. Nie przegląda historii zamówień i nie odpytuje zamówień w pętli.
Nowe opłacone zamówienie (zdarzenie READY_FOR_PROCESSING): aplikacja pobiera jego szczegóły z GET /order/checkout-forms/{id} i zapisuje je w bazie danych firmy.
Dokument w ERP. Tuż przed utworzeniem dokumentu aplikacja jeszcze raz pobiera zamówienie, żeby nie przyjąć zamówienia anulowanego w międzyczasie. Następnie tworzy w systemie ERP dokument z pozycjami, danymi dostawy i danymi do faktury.
Status realizacji. Po utworzeniu dokumentu aplikacja ustawia status PROCESSING przez PUT /order/checkout-forms/{id}/fulfillment z parametrem checkoutForm.revision, więc zmiana nie nadpisze zamówienia zmienionego w międzyczasie. Statusu nie zmienia, jeśli zamówienie ma już inny status niż „Nowe”.
Anulowania (BUYER_CANCELLED, AUTO_CANCELLED): zamówienie nie jest przyjmowane do realizacji, a jeśli dokument już powstał, pracownik dostaje powiadomienie e-mail, żeby wstrzymać wysyłkę.

4. Wykorzystywane zasoby API i uprawnienia

Zasób	Metoda	Cel	Częstotliwość
`/order/events`	GET	nowe zdarzenia zamówień	co 2 minuty, do 100 zdarzeń na zapytanie
`/order/checkout-forms/{id}`	GET	szczegóły zamówienia	2–3 razy na każde nowe zamówienie
`/order/checkout-forms/{id}/fulfillment`	PUT	status „W realizacji”	raz na każde zamówienie
`/me`	GET	sprawdzenie połączenia	tylko ręcznie, z ustawień aplikacji

Wymagane zakresy: odczyt i zapis zamówień (allegro:api:orders:read, allegro:api:orders:write) oraz odczyt profilu (allegro:api:profile:read). Aplikacja nie korzysta z zasobów ofert, płatności, rozliczeń, wiadomości ani dyskusji.

Przy obecnej skali sprzedaży (kilkanaście zamówień dziennie) aplikacja wykonuje około tysiąca zapytań na dobę, głównie odczyt dziennika zdarzeń – daleko poniżej limitów API.

5. Autoryzacja

OAuth 2.0 device flow: pracownik uprawniony do konta MARINOX loguje się raz w przeglądarce i potwierdza dostęp. Aplikacja nie zna i nie przechowuje loginu ani hasła do konta Allegro.
Token dostępowy jest odświeżany automatycznie przed wygaśnięciem. Odświeżanie jest zabezpieczone blokadą w bazie danych, więc refresh token nie zostanie użyty dwa razy.
Każde zapytanie niesie nagłówek User-Agent identyfikujący aplikację, również przy logowaniu i odświeżaniu tokenu.

6. Dane osobowe i bezpieczeństwo

Zakres: dane z zamówienia potrzebne do jego realizacji i wystawienia dokumentu sprzedaży – imię i nazwisko lub nazwa firmy, adres dostawy, dane do faktury (w tym NIP), telefon, adres e-mail w postaci udostępnionej przez Allegro, metoda dostawy i punkt odbioru, komentarz kupującego.
Cel: wyłącznie realizacja zamówienia (kompletacja, wysyłka, dokumenty sprzedaży). Dane nie są używane do marketingu ani przekazywane podmiotom trzecim innym niż przewoźnik realizujący dostawę.
Miejsce przechowywania: baza danych systemu ERP firmy, na serwerach w infrastrukturze MARINOX. Dostęp mają tylko pracownicy obsługujący zamówienia oraz konto techniczne aplikacji o ograniczonych uprawnieniach.
Transmisja: komunikacja z API Allegro wyłącznie przez HTTPS. Aplikacja działa w sieci wewnętrznej firmy i nie udostępnia żadnego interfejsu z zewnątrz.
Sekrety: Client Secret i tokeny są przechowywane w bazie danych firmy z dostępem ograniczonym do konta aplikacji, nie w kodzie źródłowym.

7. Obsługa błędów

Pozycja w dzienniku zdarzeń jest zapamiętywana dopiero po poprawnym przetworzeniu zdarzenia, więc przerwa w działaniu nie powoduje utraty zamówień.
Ponowne przetworzenie tego samego zamówienia nie tworzy drugiego dokumentu.
Błędy odpowiedzi API są zapisywane w dzienniku aplikacji wraz z identyfikatorem Trace-Id. Zamówienia, których nie da się przetworzyć automatycznie, trafiają do pracownika z powiadomieniem e-mail.

8. Kontakt

MARINOX Sp. z o.o.
ul. PAderewskiego 56B
42-660 Kalety
Osoba odpowiedzialna za integrację: Marcin Dziuk, marcin.dziuk@marinox.pl