DRIVEUP Kasa

Dokumentacja aplikacji korzystającej z Allegro REST API
DRIVEUP Sp. z o. o. · NIP 6751827795 · wersja 1.0

1. Cel aplikacji

Sprzedajemy akcesoria samochodowe (chlapacze) na koncie decorauto_pl. Zgodnie z dokumentem celnym towar sklasyfikowany jest do CN 8708 29 90 99, a części i akcesoria do pojazdów silnikowych są wyłączone ze zwolnień z obowiązku ewidencjonowania na kasie rejestrującej. Oznacza to, że każda sprzedaż na rzecz osoby fizycznej musi zostać zafiskalizowana od pierwszej złotówki.

Aplikacja realizuje jeden cel: po otrzymaniu płatności za nasze własne zamówienie odczytuje jego dane i wystawia paragon fiskalny na naszej kasie online (Elzab Zeta Online, obsługiwanej w usłudze zarządzania drukarką przez eparagony.pl).

Aplikacja jest wewnętrznym narzędziem jednej firmy. Nie jest udostępniana innym sprzedawcom, nie ma użytkowników zewnętrznych i nie jest produktem komercyjnym.

2. Jak aplikacja działa

Aplikacja to usługa działająca na naszym serwerze, bez interfejsu przeglądarkowego.

  1. Cyklicznie, co 60 sekund, odpytuje dziennik zdarzeń zamówień na naszym koncie.
  2. Reaguje wyłącznie na zdarzenie READY_FOR_PROCESSING, czyli moment, w którym zamówienie zostało opłacone lub wybrano płatność przy odbiorze.
  3. Pobiera szczegóły tego zamówienia, aby poznać pozycje, ilości, kwoty i walutę.
  4. Pomija zamówienia firm posiadających NIP, ponieważ nie podlegają one ewidencji na kasie rejestrującej.
  5. Przelicza kwoty na złote po kursie NBP, jeśli sprzedaż była w innej walucie.
  6. Wysyła paragon do operatora kasy fiskalnej i zapisuje wynik operacji.

Stan przetworzonych zamówień przechowujemy lokalnie, aby ponowienie po błędzie sieciowym nie spowodowało wystawienia drugiego paragonu do tej samej sprzedaży.

3. Wykorzystanie publicznego API Allegro

Aplikacja korzysta wyłącznie z dwóch zasobów, obu w trybie odczytu:

ZasóbMetodaPo co
/order/eventsGET wykrycie momentu opłacenia zamówienia
/order/checkout-forms/{id}GET pozycje, kwoty, waluta oraz ewentualny NIP nabywcy

Uprawnienia

Aplikacja prosi o jedno uprawnienie: allegro:api:orders:read. Nie prosi o żadne uprawnienia zapisu. Nie tworzy, nie modyfikuje ani nie usuwa niczego w Allegro: nie zmienia ofert, stanów magazynowych i statusów zamówień, nie wystawia też dokumentów po stronie Allegro.

Nagłówek User-Agent

Każde żądanie zawiera stały, jednoznaczny identyfikator aplikacji:

User-Agent: DRIVEUP-Paragony/1.0 (+https://fiskalizacja.decorauto.com.pl/)

Zmieniany jest wyłącznie numer wersji przy aktualizacji oprogramowania.

Obciążenie API

Jedno zapytanie o dziennik zdarzeń na minutę oraz jedno zapytanie o szczegóły na każde opłacone zamówienie. Przy naszej skali, około 100–200 zamówień miesięcznie, daje to rząd 1500 zapytań dziennie. Dziennik odczytujemy przyrostowo, zapamiętując identyfikator ostatniego zdarzenia, więc nie pobieramy tych samych danych wielokrotnie. Odpowiedzi 5xx i 429 obsługujemy z odczekaniem i wykładniczym wydłużaniem przerw.

4. Autoryzacja

Aplikacja działa na serwerze bez dostępu do przeglądarki, dlatego używa OAuth 2.0 Device Flow (grant_type: device_code), zgodnie z wytycznymi Allegro.

  1. Aplikacja występuje o device_code oraz user_code.
  2. Właściciel konta decorauto_pl potwierdza kod w przeglądarce, logując się bezpośrednio w Allegro. Aplikacja nigdy nie otrzymuje ani nie przechowuje loginu i hasła użytkownika.
  3. Po potwierdzeniu aplikacja odbiera access_token oraz refresh_token.
  4. Token dostępowy odświeżany jest automatycznie przed wygaśnięciem (grant_type: refresh_token).

Autoryzacja dotyczy wyłącznie jednego konta, naszego własnego. Aplikacja nie obsługuje logowania innych użytkowników i nie pośredniczy w dostępie do cudzych kont. Właściciel konta może w dowolnym momencie cofnąć dostęp w ustawieniach Allegro, co natychmiast unieważnia tokeny.

Przechowywanie danych dostępowych

Dane uwierzytelniające nie są nikomu przekazywane. Do operatora kasy fiskalnej trafia wyłącznie treść paragonu: nazwy pozycji, ilości, kwoty i stawki VAT. Nigdy klucz API, sekret klienta ani tokeny Allegro.

5. Zgodność z regulaminem REST API Allegro

WymaganieJak spełniamy
Jednoznaczna identyfikacja aplikacji stały User-Agent z nazwą, wersją i odnośnikiem do tej strony
Poufność klucza API i sekretu klienta przechowywane tylko na naszym serwerze, bez udostępniania podmiotom trzecim
Minimalny zakres uprawnień jedno uprawnienie odczytu, zero uprawnień zapisu
Prawidłowa autoryzacja użytkownika OAuth 2.0 Device Flow, bez zbierania haseł, z możliwością cofnięcia dostępu
Racjonalne korzystanie z zasobów odczyt przyrostowy, jedno zapytanie na minutę, obsługa limitów i ponowień
Ochrona danych osobowych dane nabywcy nie są zapisywane, przechowujemy wyłącznie identyfikator zamówienia, kwotę i status fiskalizacji

Zakres przetwarzanych danych

Aplikacja nie buduje bazy klientów. Z zamówienia wykorzystywane są nazwy i ilości pozycji, kwoty, waluta oraz informacja, czy nabywca podał NIP. Dane te są potrzebne wyłącznie do poprawnego wystawienia paragonu i wynikają z obowiązku ewidencji sprzedaży. Imię, nazwisko i adres nabywcy nie są zapisywane w naszej bazie.

6. Kontakt

DRIVEUP Sp. z o. o., ul. Mogilska 40/26, 31-546 Kraków
NIP 6751827795 · KRS 0001236136
Kontakt techniczny: shop@decorauto.pl