Task Description

It is necessary to connect the site tetyafanya.online to WEB API PRRO Cashälot, so that after a successful online payment, a fiscal receipt is automatically generated and sent to the DPS, and the fiscal details are saved in the order and sent to the client (link/QR/PDF).

The contractor needs to implement a full cycle: opening/closing shifts, registering receipts (including cancellations for returns), Z-reports, handling offline mode, logging, and securely storing keys KEP/SmartID/PIN.

Required Result (what should work)

1. Auto-fiscalization upon payment
   After the webhook "successful payment" from the payment provider, the site calls RegisterCheck in Cashälot:

   • with AutoOpenShift=true (if the shift is not open — open automatically),

   • get Url/QR of the receipt (for the order tab and the email to the client),

   • save NumFiscal (fiscal number), date/time, and status (online/offline).

     
     

2. Returns / cancellations
   On the event "refund/cancellation" — register the cancellation receipt via RegisterCheck (DOCSUBTYPE=CheckStorno) by passing the details of the original receipt (StornedCheck).

   
   

3. Shift and Z-report

   • Auto-close the shift via CloseShift with the parameter ZRepAuto=true (if Z has not yet been generated).

   • Ability to manually call RegisterZRep from the admin panel.

   • View the totals of the current shift via LastShiftTotals.

     
     

4. Offline mode
   In case of FSKO unavailability, work offline: accumulate documents, then automatically go online and re-register offline receipts; in case of desynchronization — Cleanup.

   
   

5. Receiving receipt/Z
   Ability to pull the completed receipt/Z from the server by fiscal number (GetCheck/GetZRep) for display/resending to the client.

   
   

6. Security of keys and settings

   • Add a settings screen: upload certificate/key (or SmartID/KeyPin), bind to the required NumFiscal PRRO.

   • Store secrets outside web-root, in .env/protected config storages.

   • Support for simplified mode KeyPin (if enabled in the back office), where Certificate/PrivateKey/Password are not passed in commands.

     
     

7. Admin interface

   • In the order card: fiscalization status, NumFiscal, link to receipt (Url), QR (img), offline/online flag, log of the last attempts.

   • Buttons: "Resend receipt", "Generate Z-report", "Close shift", "Cleanup/synchronization (Cleanup)".

     
     

8. Notifications to the client

   • After a successful payment, send an email with a link/QR to the receipt (and/or an attachment of HTML/PDF visualization, if Visualization/VisAsHtml is used).

     
     

9. Logs and resilience

   • Log of API requests/responses (secure masking of personal and key data).

   • Retries on temporary failures; queue for resending.

   • Alerts in the admin panel on ErrorCode/ErrorMessage. 

   • Technical Implementation Details (what exactly the developer should do)

     1) Connection to Cashälot

     • Configure Setup for storing KEP/SmartID parameters (Certificate/PrivateKey/Password/UseSmartId) or use KeyPin according to the enabled integration in the back office
       At startup, check server availability (ServerState) and PRRO status (TransactionsRegistrarState).
       
       

     • 2) Flow "Payment → Receipt"

       • Listen to the payment system webhook "successfully paid".

       • Form the receipt structure (service, amount, taxes/excluding VAT), call RegisterCheck with:

         • NumFiscal = fiscal number of PRRO;

         • Check = receipt data (service/item/total/payment);

         • AutoOpenShift=true (if the shift is not open, open automatically);

         • GetQrCode=true, if necessary Visualization/VisAsHtml.

           
           

       • API response: save NumFiscal, NumLocal, OrderDateTime, flag Offline, Url and QrCode in the order.

         
         

     • 3) Refund/cancellation

       • On the refund event — RegisterCheck with type CheckStorno, passing StornedCheck (or StornedCheckToConvert) to correctly calculate the shift totals.

         
         

     • 4) Shift and Z-report

       • When closing the day — CloseShift (ZRepAuto=true);

       • Alternative: a separate button RegisterZRep (if needed before closing).

       • View shift totals — LastShiftTotals (for the admin screen).

         
         

     • 5) Offline / desynchronization

       • When OfflineDocumentsPresent → periodically attempt auto-registration;

       • When InconsistentRegistrarState → run Cleanup (with informing the admin), where necessary.

         
         

     • 6) Receiving documents

       • Upon admin request — GetCheck/GetZRep with the option Visualization and GetQrCode (for resending to the client).

         
         

   •