====== Інтеграція з сервісом фіскалізації Dreamkas ====== Варто відразу обмовитися, що для користувачів, які працюють і приймають оплати за межами мордора, цей модуль - **НЕ НУЖЕН**. [[http://ubilling.net.ua/?module=fnpages&pid=bobrpay|{{ :buy-88.png?nolink&|}}]] ===== Итак - что это за штука? Чи варто перекладати на українську? ===== Эта штука призвана обеспечить тесное взаимодействие с российским сервисом фискализации [[https://dreamkas.ru/|Dreamkas]] и поможет операторам и провайдерам строго следовать букве закона **54-Ф3**, особенно его поправкам и изменениям, вступившим в силу с 01.07.2019.\\ Ещё одно важное замечание заключается в том, что работать это всё будет только при условии наличия у вас [[https://kabinet.dreamkas.ru/api/#fiskalizaciya-chekov-po-api|ККТ "Дримкас Ф" или "Касса Ф"]]. ===== И зачем оно мне? Что оно вообще умеет делать конкретно? ===== Этот модуль позволит вам фискализировать(то есть - выбить чек на вашем ККТ) оплаты принятые от Интернет или [[ukv|УКВ]] пользователей прямо из их профиля в момент внесения оплаты. Так же модуль позволяет гибкий выбор настроек фискализации: выбор ККТ, типа налогообложения, типа денежных средств и, конечно же, наименование торговой позиции. И все это прямо в момент непосредственного внесения абонплаты. Вот как это выглядит на примере профиля УКВ юзера:\\ {{ :drks12.png?800 |}}\\ Но, конечно же, это - не самое главное. Самое главное - это возможность очень плотного взаимодействия с модулем "Обработка банковских выписок 2" aka banksta2. ===== Какая "banksta2"? Почему я о ней до сих пор не слышал? ===== Модуль [[banksta2|Обработка банковских выписок 2]] создан для импорта оплат из различных выписок различных банков от пользователей Интернет и УКВ. **Допустим, мне интересно - что нужно сделать, чтобы все это "взлетело"?** ====== Настройка, включение, нюансы ====== Для "запуска" этого всего нам будет необходимо конечно же включить работу с API в личном кабинете Dreamkas, а так же нам понадобятся 2 основные опции //alter.ini//: //DREAMKAS_ENABLED// и //DREAMKAS_AUTH_TOKEN//. Первая, как несложно догадаться, включает или выключает, собственно, модуль, а вторая должна содержать строку-token для авторизации по API, полученную в том же личном кабинете сервиса Dreamkas. После чего мы должны лицезреть вот такую кнопку на панели задач:\\ {{ :drks16.png?128 |}}\\ нажав которую мы увидим следующее:\\ {{:drks1.png?800|}} {{:drks2.png?800|}} {{:drks3.png?800|}} {{:drks4.png?800|}} Как видите - там всё вполне себе наглядно(ну, на сколько оно может быть таковым) и каких-либо объяснений не требует. Единственное, пожалуй, что стоит отметить - никакие сущности редактированию не подлежат. То есть, если вы рассчитывали на копию личного кабинета Dreamkas в вашем биллинге - то ваши ожидания не оправдались. А мы плавно переходим к мало очевидным деталям. ===== Нюансы и тонкости ===== Первым стоит отметить очень важный момент который, на первый взгляд, имеет мало отношения к деньгам и фискальным операциям в частности. Но это только на первый взгляд. Заключается этот момент в том, что абсолютно каждый ваш юзер, деньги которого вы планируете фискализировать, **ОБЯЗАТЕЛНЬНО ДОЛЖЕН** иметь заполненное поле **мобильного** телефона у себя в профиле. Да, именно мобильного телефона и никакого другого. Да, это именно затем, чтобы сервис знал, куда вашему клиенту отправить фискальный чек о прошедшей оплате(или ссылку на него). Да, для пользователей Интернета можно указать ещё и e-mail.\\ \\ Вторым мало очевидным нюансом может стать привязка определенной торговой позиции к конкретно взятому сервису(Интернет или УКВ), что позволяет в момент фискализации оплаты автоматически выбирать торговую позицию. И если для оплат, фискализируемых при внесении денег из профиля пользователя это можно расценивать чисто как маленькое удобство, то для банковских выписок это можно считать обязательным, дабы избежать мазохизма с выбором торговой позиции для **//каждой//** из 10 или 20 или 50 оплат в выписке. Делается это в разделе "Торговые позиции"(предпоследний скрин выше) с помощью вот этих нехитрых элементов управления:\\ {{ :drks7.png?328 |}}\\ ===== По тонкостям вроде все - поговорим о некоторых фичах ===== Пожалуй, есть всего пара-тройка фич, о которых стоит упомянуть вот прям отдельно. Это оповещения о всяческом происходящем в духе [[fwtbt|FWTBT]], кэширование и веб-хуки. Скорее всего вы не могли не заметить кучку необязательных //DREAMKAS_*// опций в //alter.ini//. Вот с их помощью мы и можем влиять на вышеописанные фичи. Итак - поехали: ==== Кэширование ==== Для того, чтобы веб интерфейс профилей Интернет и УКВ пользователей всегда оставался таким же плавным, быстрым и отзывчивым как раз и была применена подсистема кэширования. Чтобы ваш биллинг не ломился на сервер Dreamkas за данными для заполнения формы фискализации каждый раз, когда вы открываете профиль пользователя. Или тем более - открываете импортированную банковскую выписку. Да и вообще - чтобы дергать сервер Dreamkas по минимуму, ибо он этого не любит(так вскользь было упомянуто где-то у них в документации). Время жизни кэша управляется опцией //DREAMKAS_CACHE_LIFETIME// и по умолчанию равняется 1800 секунд или полчаса. Так же предусмотрена кнопка для мануального управления и принудительного обновления кэша Dreamkas. ==== Оповещения ==== Задуманы работать только в паре с веб-хуками. Умеют уведомлять обо всем, что "прилетает" от сервера Dreamkas. Носят скорее отладочный характер и будут больше полезны админам для разбора полетов, чем бухгалтеру/кассиру, у которого и так хватает задач, кроме того, чтобы разбирать какие-то там сообщения от какого-то там сервиса. Потому для этих целей предусмотрено включение уведомлений только для конкретных админ-юзеров с помощью опции //DREAMKAS_ADMINS_ALLOWED// в которую нужно через запятую записать логины админ-юзеров, которым мы хотим показывать эти оповещения. Так же имеются и другие опции управления уведомлениями: * //DREAMKAS_NOTIFICATIONS_ENABLED// - собственно включает/выключает оповещения. * //DREAMKAS_CACHE_CHECK_INTERVAL// - как часто проверять наличие новых оповещений. По умолчанию - 8 секунд. * //DREAMKAS_POPUP_TIMEOUT// - время жизни(отображения на экране) каждого отдельно взятого оповещения. По умолчанию - 10 секунд. * //DREAMKAS_NOTIFY_ANYWHERE// - уведомлять везде, а не только на панели задач Убиллинга. По умолчанию - включено. * //DREAMKAS_DESKTOP_NOTIFICATIONS// - отображать оповещения на рабочем столе. Работает только в FireFox, остальные ВСЕ браузеры нынче требуют HTTPS для работы этой фичи.\\ Выглядит это все примерно вот так:\\ {{:drks8.png?700|}} {{:drks9.png?800|}} {{:drks10.png?800|}} \\ А на последнем скриншоте мы можем лицезреть самое верхнее уведомление ярко демонстрирующее, что произойдет при попытке фискализации оплаты для пользователя у которого **НЕ ЗАПОЛНЕНО** поле мобильный телефон в профиле. ==== Веб-хуки ==== Очень полезная вещь крайне рекомендуемая к включению и использованию. Призвана избавить нас от рутины собственноручного поллинга(опроса, то бишь) сервера Dreamkas с помощью cron или иных аналогичных механизмов, чтобы узнать статус той или иной сущности. Вся прелесть заключается в том, что сервер Dreamkas сам проинформирует нас о том или ином событии или изменении, как только оно произойдет. Наша основная и, пожалуй, единственная задача - дать ему URL, на который он и будет сообщать о всяком разном. Ну и да - есть возможность указать, о каком именно всяком мы хотели бы узнавать. Базируется эта штука на вызове функции-обработчика из [[remoteapi|RemoteAPI]], но не требует никаких манипуляций с cron. Выглядит примерно вот так:\\ {{:drks5.png?700|}} {{:drks6.png?800|}} \\ То есть, по сути, вся настройка сводится к тому, чтобы создать какой вам хочется/можется URL, который указывается в верхней строке на последнем скриншоте и выбрать события, о которых мы бы хотели узнавать. Ну и конечно же не забыть добавить это все в конфиг хостов нашего веб-сервера. Мы юзаем Apache и у нас это выглядит как-то примерно так:\\ ServerName billing.webhooks.net ServerAlias www.billing.webhook.net DocumentRoot /var/www/billing RewriteEngine On RewriteCond %{QUERY_STRING} !^\/\?module=remoteapi&key=.+ RewriteCond %{QUERY_STRING} !.+&action=dreamkas¶m=.+$ RewriteRule ^.* - [F,L] LogLevel info LogLevel info rewrite:trace7 ErrorLog /var/log/apache2/billing_webhook_error.log CustomLog /var/log/apache2/billing_webhook_access.log common Повторюсь - это только пример и вы вольны настроить свой веб-сервер как вам заблагорассудится. Кроме того, у вас ведь может быть даже и не Apache. ===== В заключение ===== Ну вот, пожалуй, и все по нюансам и настройкам. Разве что стоит ещё кратко упомянуть опции //aletr.ini//, оставшиеся за кадром:\\ * //DREAMKAS_ALWAYS_FISCALIZE_ALL// - флажок "Фискализировать этот платеж?" будет всегда отмечен. Как в профилях пользователей, так и в банковской выписке. * //DREAMKAS_DEFAULT_CASH_MACHINE_ID// - если у вас имеется более одного кассового аппарата - здесь можно указать ID того, который чаще всего используется. * //DREAMKAS_DEFAULT_TAX_TYPE// - тип налогообложения, который будет использоваться по умолчанию. Возможные значения: 'DEFAULT' => 'Общая', 'SIMPLE' => 'Упрощенная доход', 'SIMPLE_WO' => 'Упрощенная доход минус расход', 'ENVD' => 'Единый налог на вмененный доход', 'PATENT' => 'Патентная система налогообложения'