Opis zadania

Trzeba podłączyć stronę tetyafanya.online do WEB API PPR Cashälot, aby po udanej płatności online automatycznie generowany był paragon fiskalny i wysyłany do DPS, a dane fiskalne były zapisywane w zamówieniu i wysyłane do klienta (link/QR/PDF).

Wykonawca musi zrealizować pełny cykl: otwieranie/zamykanie zmiany, rejestracja paragonów (w tym storno przy zwrotach), raporty Z, obsługa trybu offline, logowanie i bezpieczne przechowywanie kluczy KEP/SmartID/PIN.

Wymagany rezultat (co powinno działać)

1. Auto-fiskalizacja przy płatności
   Po webhook „udana płatność” od dostawcy płatności strona wywołuje RegisterCheck w Cashälot:

   • z AutoOpenShift=true (jeśli zmiana nie jest otwarta — otworzyć automatycznie),

   • otrzymać Url/QR paragonu (dla zakładki zamówienia i e-maila do klienta),

   • zapisać NumFiscal (numer fiskalny), datę/czas i status (online/offline).

     
     

2. Zwroty / storno
   Po zdarzeniu „refund/odwołanie” — rejestrować paragon storno przez RegisterCheck (DOCSUBTYPE=CheckStorno) z przekazaniem danych oryginalnego paragonu (StornedCheck).

   
   

3. Zmiana i raport Z

   • Auto-zamknięcie zmiany przez CloseShift z parametrem ZRepAuto=true (jeśli Z jeszcze nie został wygenerowany).

   • Możliwość ręcznego wywołania RegisterZRep z panelu administracyjnego.

   • Podgląd wyników bieżącej zmiany przez LastShiftTotals.

     
     

4. Tryb offline
   W przypadku braku dostępu do FSKO pracować w trybie offline: akumulować dokumenty, a następnie automatycznie przejść do online i zarejestrować paragon offline; w przypadku desynchronizacji — Cleanup.

   
   

5. Pobieranie paragonu/Z
   Możliwość pobrania gotowego paragonu/Z z serwera po numerze fiskalnym (GetCheck/GetZRep) do wyświetlenia/powtórnej wysyłki do klienta.

   
   

6. Bezpieczeństwo kluczy i ustawień

   • Dodaj ekran ustawień: załaduj certyfikat/klucz (lub SmartID/KeyPin), powiązanie z odpowiednim NumFiscal PPR.

   • Przechowywanie sekretów poza web-root, w .env/chronionych magazynach konfiguracyjnych.

   • Wsparcie uproszczonego trybu KeyPin (jeśli włączone w back-office), gdzie w komendach nie przekazywane są Certificate/PrivateKey/Password.

     
     

7. Interfejs administracyjny

   • W karcie zamówienia: status fiskalizacji, NumFiscal, link do paragonu (Url), QR (img), flaga offline/online, log ostatnich prób.

   • Przyciski: „Ponownie wyślij paragon”, „Wygeneruj raport Z”, „Zamknij zmianę”, „Czyszczenie/synchronizacja (Cleanup)”.

     
     

8. Powiadomienia do klienta

   • Po udanej płatności wysłać e-mail z linkiem/QR do paragonu (i/lub załącznik HTML/PDF wizualizacji, jeśli używane jest Visualization/VisAsHtml).

     
     

9. Logi i odporność

   • Dziennik zapytań/odpowiedzi API (bezpieczne maskowanie danych osobowych i kluczowych).

   • Retry przy tymczasowych awariach; kolejka do ponownej wysyłki.

   • Alerte w panelu administracyjnym przy ErrorCode/ErrorMessage. 

   • Szczegóły techniczne realizacji (co dokładnie ma zrobić programista)

     1) Podłączenie do Cashälot

     • Skonfigurować Setup do przechowywania parametrów KEP/SmartID (Certificate/PrivateKey/Password/UseSmartId) lub użyć KeyPin zgodnie z włączoną integracją w back-office
       Przy starcie sprawdzić dostępność serwera (ServerState) i stan PPR (TransactionsRegistrarState).
       
       

     • 2) Przepływ „Płatność → paragon”

       • Słuchać webhooka systemu płatności „płatność zakończona sukcesem”.

       • Uformować strukturę paragonu (usługa, kwota, podatki/bez VAT), wywołać RegisterCheck z:

         • NumFiscal = numer fiskalny PPR;

         • Check = dane paragonu (usługa/pozycja/całkowita/płatność);

         • AutoOpenShift=true (jeśli zmiana nie jest otwarta, otworzyć automatycznie);

         • GetQrCode=true, w razie potrzeby Visualization/VisAsHtml.

           
           

       • Odpowiedź API: zapisać NumFiscal, NumLocal, OrderDateTime, flaga Offline, Url i QrCode w zamówieniu.

         
         

     • 3) Zwrot/odwołanie

       • Na zdarzenie zwrotu — RegisterCheck z typem CheckStorno, przekazując StornedCheck (lub StornedCheckToConvert), aby poprawnie obliczyć wyniki zmiany.

         
         

     • 4) Zmiana i raport Z

       • Przy zamykaniu dnia — CloseShift (ZRepAuto=true);

       • Alternatywa: osobny przycisk RegisterZRep (jeśli potrzebne przed zamknięciem).

       • Podgląd wyników zmiany — LastShiftTotals (dla ekranu administracyjnego).

         
         

     • 5) Offline / desynchronizacja

       • Przy OfflineDocumentsPresent → okresowo próbować auto-rejestracji;

       • Przy InconsistentRegistrarState → uruchomić Cleanup (z informowaniem administratora), gdzie to konieczne.

         
         

     • 6) Pobieranie dokumentów

       • Na żądanie administratora — GetCheck/GetZRep z opcją Visualization i GetQrCode (do ponownej wysyłki do klienta).

         
         

   •