Интеграция с сервисом фискализации Dreamkas

Стоит сразу оговориться, что для пользователей, работающих и принимающих оплаты за пределами Российской Федерации, этот модуль - НЕ нужОн.

Итак - что это за штука?

Эта штука призвана обеспечить тесное взаимодействие с российским сервисом фискализации Dreamkas и поможет операторам и провайдерам строго следовать букве закона 54-Ф3, особенно его поправкам и изменениям, вступившим в силу с 01.07.2019.
Ещё одно важное замечание заключается в том, что работать это всё будет только при условии наличия у вас ККТ "Дримкас Ф" или "Касса Ф".

И зачем оно мне? Что оно вообще умеет делать конкретно?

Этот модуль позволит вам фискализировать(то есть - выбить чек на вашем ККТ) оплаты принятые от Интернет или УКВ пользователей прямо из их профиля в момент внесения оплаты. Так же модуль позволяет гибкий выбор настроек фискализации: выбор ККТ, типа налогообложения, типа денежных средств и, конечно же, наименование торговой позиции. И все это прямо в момент непосредственного внесения абонплаты. Вот как это выглядит на примере профиля УКВ юзера:

Но, конечно же, это - не самое главное. Самое главное - это возможность очень плотного взаимодействия с модулем «Обработка банковских выписок 2» aka banksta2.

Какая "banksta2"? Почему я о ней до сих пор не слышал?

Модуль «Обработка банковских выписок 2» создан для импорта оплат из различных выписок различных банков от пользователей Интернет и УКВ. Основной особенностью, отличающей этот модуль от уже имеющегося похожего функционала, является возможность гибкой - очень гибкой - настройки импорта этих самых платежей, а так же поддержка отнюдь не малого количества форматов файлов для импорта. Более того, для каждого конкретного типа выписки вы можете создать и сохранить шаблон соответствия полей и настроек импорта, чтобы потом подгружать его в один клик. Для его включения вам понадобятся вполне себе «self-explanationary» опции alter.ini «BANKSTA2_*». Выглядит это всё примерно так:

Ок, и в чём прэлесть?

А в том, что если вам в 2019 году таки ещё приходится обрабатывать банковские выписки полученные в электронном виде из различных клиент-банков и прочих источников, то потратив 15 минут жизни на настройку и сохранение шаблона опций импорта той или иной выписки, вы получаете практически моментальную обработку каждой выписки без нудного сидения склоня голову над распечаткой с линейкой, периодически поднимая глаза на монитор и постоянно перехватывая рукой то мышь, то ручку, чтобы отметить галочкой внесенную оплату. А теперь представьте, что это все совмещено с модулем Dreamkas? И вам больше не нужно каждую оплату пробивать руками на вашем кассовике. Все оплаты фискализируются в один клик! Выглядит это все как-то так:

На скриншоте выше вы можете заметить, что успешно фискализированные оплаты получают ID фискальной операции и ID проведенного чека. Если же по какой либо причине фискализация оплаты не удалась - ее можно фискализировать повторно.

Допустим, мне интересно - что нужно сделать, чтобы все это «взлетело»?

Настройка, включение, нюансы

Для «запуска» этого всего нам будет необходимо конечно же включить работу с API в личном кабинете Dreamkas, а так же нам понадобятся 2 основные опции alter.ini: DREAMKAS_ENABLED и DREAMKAS_AUTH_TOKEN. Первая, как несложно догадаться, включает или выключает, собственно, модуль, а вторая должна содержать строку-token для авторизации по API, полученную в том же личном кабинете сервиса Dreamkas. После чего мы должны лицезреть вот такую кнопку на панели задач:

нажав которую мы увидим следующее:

Как видите - там всё вполне себе наглядно(ну, на сколько оно может быть таковым) и каких-либо объяснений не требует. Единственное, пожалуй, что стоит отметить - никакие сущности редактированию не подлежат. То есть, если вы рассчитывали на копию личного кабинета Dreamkas в вашем биллинге - то ваши ожидания не оправдались. А мы плавно переходим к мало очевидным деталям.

Нюансы и тонкости

Первым стоит отметить очень важный момент который, на первый взгляд, имеет мало отношения к деньгам и фискальным операциям в частности. Но это только на первый взгляд. Заключается этот момент в том, что абсолютно каждый ваш юзер, деньги которого вы планируете фискализировать, ОБЯЗАТЕЛНЬНО ДОЛЖЕН иметь заполненное поле мобильного телефона у себя в профиле. Да, именно мобильного телефона и никакого другого. Да, это именно затем, чтобы сервис знал, куда вашему клиенту отправить фискальный чек о прошедшей оплате(или ссылку не него). Да, для пользователей Интернета можно указать ещё и e-mail.

Вторым мало очевидным нюансом может стать привязка определенной торговой позиции к конкретно взятому сервису(Интернет или УКВ), что позволяет в момент фискализации оплаты автоматически выбирать торговую позицию. И если для оплат, фискализируемых при внесении денег из профиля пользователя это можно расценивать чисто как маленькое удобство, то для банковских выписок это можно считать обязательным, дабы избежать мазохизма с выбором торговой позиции для каждой из 10 или 20 или 50 оплат в выписке. Делается это в разделе «Торговые позиции»(предпоследний скрин выше) с помощью вот этих нехитрых элементов управления:

По тонкостям вроде все - поговорим о некоторых фичах

Пожалуй, есть всего пара-тройка фич, о которых стоит упомянуть вот прям отдельно. Это оповещения о всяческом происходящем в духе 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 для работы этой фичи.

Выглядит это все примерно вот так:

А на последнем скриншоте мы можем лицезреть самое верхнее уведомление ярко демонстрирующее, что произойдет при попытке фискализации оплаты для пользователя у которого НЕ ЗАПОЛНЕНО поле мобильный телефон в профиле.

Веб-хуки

Очень полезная вещь крайне рекомендуемая к включению и использованию. Призвана избавить нас от рутины собственноручного поллинга(опроса, то бишь) сервера Dreamkas с помощью cron или иных аналогичных механизмов, чтобы узнать статус той или иной сущности. Вся прелесть заключается в том, что сервер Dreamkas сам проинформирует нас о том или ином событии или изменении, как только оно произойдет. Наша основная и, пожалуй, единственная задача - дать ему URL, на который он и будет сообщать о всяком разном. Ну и да - есть возможность указать, о каком именно всяком мы хотели бы узнавать. Базируется эта штука на вызове функции-обработчика из RemoteAPI, но не требует никаких манипуляций с cron. Выглядит примерно вот так:

То есть, по сути, вся настройка сводится к тому, чтобы создать какой вам хочется/можется URL, который указывается в верхней строке на последнем скриншоте и выбрать события, о которых мы бы хотели узнавать. Ну и конечно же не забыть добавить это все в конфиг хостов нашего веб-сервера. Мы юзаем Apache и у нас это выглядит как-то примерно так:

<VirtualHost *:54321>
    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&param=.+$
    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
</VirtualHost>

Повторюсь - это только пример и вы вольны настроить свой веб-сервер как вам заблагорассудится. Кроме того, у вас ведь может быть даже и не Apache.

В заключение

Ну вот, пожалуй, и все по нюансам и настройкам. Разве что стоит ещё кратко упомянуть опции aletr.ini, оставшиеся за кадром:

  • DREAMKAS_ALWAYS_FISCALIZE_ALL - флажок «Фискализировать этот платеж?» будет всегда отмечен. Как в профилях пользователей, так и в банковской выписке.
  • DREAMKAS_DEFAULT_CASH_MACHINE_ID - если у вас имеется более одного кассового аппарата - здесь можно указать ID того, который чаще всего используется.
  • DREAMKAS_DEFAULT_TAX_TYPE - тип налогообложения, который будет использоваться по умолчанию. Возможные значения:
    'DEFAULT'   => 'Общая',
    'SIMPLE'    => 'Упрощенная доход',
    'SIMPLE_WO' => 'Упрощенная доход минус расход',
    'ENVD'      => 'Единый налог на вмененный доход',
    'PATENT'    => 'Патентная система налогообложения'
 
dreamkas.txt · Последние изменения: 2019/08/20 16:07 — bobr
 
За исключением случаев, когда указано иное, содержимое этой вики предоставляется на условиях следующей лицензии: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki