Описание задачи

Нужно подключить сайт tetyafanya.online к WEB API ПРРО Cashälot, чтобы после успешной онлайн-оплаты автоматически формировался фискальный чек и отправлялся в ДПС, а фискальные реквизиты сохранялись в заказе и отправлялись клиенту (ссылка/QR/PDF).

Исполнителю необходимо реализовать полный цикл: открытие/закрытие смены, регистрация чеков (в т.ч. сторно при возвратах), Z-отчёты, обработка офлайн-режима, логирование и безопасное хранение ключей КЭП/SmartID/PIN.

Требуемый результат (что должно работать)

1. Авто-фискализация при оплате
   После webhook «успешная оплата» от платёжного провайдера сайт вызывает RegisterCheck в Cashälot:

   • с AutoOpenShift=true (если смена не открыта — открыть автоматически),

   • получить Url/QR чека (для вкладки заказа и письма клиенту),

   • сохранить NumFiscal (фискальный №), дату/время и статус (онлайн/офлайн).

     
     

2. Возвраты / сторно
   По событию «refund/отмена» — регистрировать сторнирующий чек через RegisterCheck (DOCSUBTYPE=CheckStorno) с передачей реквизитов исходного чека (StornedCheck).

   
   

3. Смена и Z-отчёт

   • Авто-закрытие смены через CloseShift с параметром ZRepAuto=true (если Z ещё не сформирован).

   • Возможность вручную вызвать RegisterZRep из админки.

   • Просмотр итогов текущей смены via LastShiftTotals.

     
     

4. Офлайн-режим
   При недоступности ФСКО работать в офлайн: аккумулировать документы, затем автоматически перейти онлайн и дозарегистрировать офлайн-чеки; при рассинхронизации — Cleanup.

   
   

5. Получение чека/Z
   Возможность подтянуть готовый чек/Z с сервера по фискальному номеру (GetCheck/GetZRep) для отображения/повторной отправки клиенту.

   
   

6. Безопасность ключей и настроек

   • Добавить экран настройки: загрузка сертификата/ключа (или SmartID/KeyPin), привязка к нужному NumFiscal ПРРО.

   • Хранение секретов вне web-root, в .env/защищённых конфиг-хранилищах.

   • Поддержка облегчённого режима KeyPin (если включён в бек-офисе), где в командах не передаются Certificate/PrivateKey/Password.

     
     

7. Админ-интерфейс

   • В карточке заказа: статус фискализации, NumFiscal, ссылка на чек (Url), QR (img), offline/online флаг, лог последних попыток.

   • Кнопки: «Переотправить чек», «Сформировать Z-отчёт», «Закрыть смену», «Очистка/синхронизация (Cleanup)».

     
     

8. Уведомления клиенту

   • После успешной оплаты отправить e-mail с ссылкой/QR на чек (и/или вложение HTML/PDF визуализации, если используется Visualization/VisAsHtml).

     
     

9. Логи и устойчивость

   • Журнал запросов/ответов API (безопасное маскирование персональных и ключевых данных).

   • Ретраи при временных сбоях; очередь на переотправку.

   • Алерты в админке при ErrorCode/ErrorMessage. 

   • Технические детали реализации (что именно делать разработчику)

     1) Подключение к Cashälot

     • Настроить Setup для хранения параметров КЭП/SmartID (Certificate/PrivateKey/Password/UseSmartId) или использовать KeyPin согласно включённой интеграции в бек-офисе
       При старте проверять доступность сервера (ServerState) и состояние ПРРО (TransactionsRegistrarState).
       
       

     • 2) Поток «Оплата → чек»

       • Слушать webhook платёжной системы «успешно оплачено».

       • Сформировать структуру чека (услуга, сумма, налоги/без НДС), вызвать RegisterCheck c:

         • NumFiscal = фискальный номер ПРРО;

         • Check = данные чека (услуга/позиция/итог/оплата);

         • AutoOpenShift=true (если смена не открыта, открыть автоматически);

         • GetQrCode=true, при необходимости Visualization/VisAsHtml.

           
           

       • Ответ API: сохранить NumFiscal, NumLocal, OrderDateTime, флаг Offline, Url и QrCode в заказе.

         
         

     • 3) Возврат/отмена

       • На событие возврата — RegisterCheck с типом CheckStorno, передав StornedCheck (либо StornedCheckToConvert), чтобы корректно посчитались итоги смены.

         
         

     • 4) Смена и Z-отчёт

       • При закрытии дня — CloseShift (ZRepAuto=true);

       • Альтернатива: отдельная кнопка RegisterZRep (если нужно до закрытия).

       • Просмотр итогов смены — LastShiftTotals (для админ-экрана).

         
         

     • 5) Офлайн / рассинхронизация

       • При OfflineDocumentsPresent → периодически пытаться авто-регистрацию;

       • При InconsistentRegistrarState → запускать Cleanup (с информированием админа), где нужно.

         
         

     • 6) Получение документов

       • По требованию админа — GetCheck/GetZRep c опцией Visualization и GetQrCode (для повторной отправки клиенту).

         
         

   •