﻿НАЗНАЧЕНИЕ ПРОГРАММЫ

Программа BxDTO предназначена для получения чеков с сайтов интернет-магазинов, работающих на платформе 1С-Битрикс, и передачи их контрольно-кассовой технике (ККТ) для печати, записи в фискальные накопители (ФН) и передачи через интернет на серверы операторов фискальных данных (ОФД). В настоящее время программа протестирована с фискальными регистраторами АТОЛ FPrint-22ПТК, АТОЛ 42ФС, АТОЛ 11Ф, АТОЛ 30Ф, АТОЛ 77Ф. Должна работать со всеми устройствами, поддерживаемыми драйверами АТОЛ ДККТ10, кроме автономных моделей (АТОЛ 90Ф). Может потребоваться обновление прошивки ККТ для поддержки изменений по 54-ФЗ. Для поддержки ФФД 1.05 требуется прошивка 4555 или выше. 32-битная версия BxDTO может работать на Windows XP, 7, 8.x, 10, Windows Server 2003, 2012, 2016, 2019. 64-битная версия с Windows 7, 8.x, 10 и Windows Server 2012, 2016, 2019, Linux Ubuntu 18, Centos 7.

BxDTO/2.x будет корректно работать только при обновлении модуля sale на портале до версии sale 18.5.7.


УСТАНОВКА

Перед установкой BxDTO под Windows необходимо предварительно подключить ККТ, установить необходимые драйверы, убедиться в работоспособности подключения с помощью программ из комплекта АТОЛ ДККТ10, DTO9 или DTO8 "Тест драйверов устройств печати", запомнить номер COM-порта (либо IP-адрес и TCP-порт в случае соединения с ККТ по сети), с которым тесты прошли успешно.

После подключения ККТ запустите установщик BxDTO-<версия>-<платформа>.exe или BxDTO-<версия>-<платформа>.msi и следуйте указаниям мастера установки.

64-битная версия по умолчанию устанавливается в каталог "C:\Program Files\BxDTO", 32-битная в "C:\Program Files (x86)\BxDTO". В описании ниже примеры путей указаны для 32-битного варианта.

Версия для Linux устанавливается из DEB- либо RPM-пакета, после установки доступна команда BxDTO, поддерживающая те же опции, что и Windows-версия. Добавляется также служба /etc/systemd/system/bxdto.service.
 

НАСТРОЙКА

Для настройки необходимо знать номер COM-порта контрольно-кассовой машины (ККМ) или нескольких портов, если подключены несколько устройств одновременно, и URL сайта магазина, с которого будут приниматься чеки. Этот URL может выглядеть как https://<site>/bitrix/tools/sale_check_print.php?hash=<hash>, получить его можно в административном интерфейсе сайта. URL'ов тоже может быть несколько, если необходима работа с несколькими сайтами. Если используется одна ККМ и она подключена по USB, то номер её COM-порта можно не указывать (убрать опцию "--kkm-port N"), драйверы ДККТ10 найдут подключение автоматически.

BxDTO работает без интерфейса как системная служба. Номера портов и URL указываются в файле BxDTO-from-svc.bat, который автоматически запускается при старте службы из диспетчера служб. Пример такого файл устанавливается в "C:\Program Files (x86)\BxDTO\bin\BxDTO-from-svc.bat.SAMPLE" ("/usr/bin/BxDTO-from-svc.sh.SAMPLE" под Linux), если использовался путь установки по умолчанию. Скопируйте BxDTO-from-svc.bat.SAMPLE в BxDTO-from-svc.bat и отредактируйте BxDTO-from-svc.bat. Текстовый редактор для изменения этого файла должен быть запущен в режиме Администратора, так как система защищает "Program Files" от изменений. Под Linux после редактирования файла выполните "chmod +x BxDTO-from-svc.sh". Изначально файл под Windows выглядит так:

start BxDTO.exe --worker --kkm-port 3 --print --name "Fprint22" --log
start BxDTO.exe --dispatcher --url http://192.168.2.3/bitrix/tools/sale_check_print.php?hash=2b0a11437fe3439d55f55c93c22f8129 --name "Fprint22" --log

под Linux так:

#!/bin/bash

nohup /usr/bin/BxDTO --worker --print --name "Fprint22" --log &
nohup /usr/bin/BxDTO --dispatcher --url http://192.168.2.3/bitrix/tools/sale_check_print.php?hash=2b0a11437fe3439d55f55c93c22f8129 --name "Fprint22" --log &


- запускаются два экземпляра процесса BxDTO в разных режимах "dispatcher" и "worker". Dispatcher взаимодействует с сайтом магазина, Worker взаимодействует с ККТ. Dispatcher направляет полученные чеки в очередь на печать, Worker берёт из очереди чеки, направленные на печать заданной (при формировании чека на сайте) ККМ. ККМ может быть подключено несколько, на разных COM-портах или разных сетевых размещениях, в этом случае должно быть запущено несколько worker-процессов, по одному для каждого порта - например, файл BxDTO-from-svc.bat может иметь вид:

start BxDTO.exe --worker --kkm-port 3 --print --name "Fprint22" --log
start BxDTO.exe --worker --kkm-port 7 --name "Atol42FS" --log
start BxDTO.exe --worker --kkm-ip-port 5555 --kkm-ip-addr 192.168.2.125 --name "Fprint22net" --print --log 
start BxDTO.exe --dispatcher --url http://192.168.2.3/bitrix/tools/sale_check_print.php?hash=2b0a11437fe3439d55f55c93c22f8129 --name "Fprint22" --log

Если --kkm-port не указывать, то драйвер самостоятельно найдет порт ККМ, подключенной по USB. При подключении ККМ через Ethernet нужно указать IP-адрес и номер TCP-порта ККМ в параметрах --kkm-ip-addr, --kkm-ip-port.

Параметр --name может быть произвольным (в кодировке ASCII), он передаётся на сервер вместе с другими параметрами подключенных касс, кроме того имя используется для разделения протоколов работы (логов) разных процессов. Каждая ККМ имеет уникальный заводской серийный номер, он автоматически считывается worker-процессами с подключенных ККМ и передаётся на сервер dispatcher-процессом. Именно заводской номер ККМ используется для идентификации ККМ при передаче чека на обработку в заданную ККМ. 

Очередей тоже может быть несколько, если используется параметр "--mq имя_очереди" в параметрах dispatcher- и worker-процессов. В каждой очереди может быть свой dispatcher-процесс со своим URL и worker-процессы со своим набором ККМ. Соответственно в BxDTO-from-svc.bat может быть произвольное число строк "start BxDTO...".


ЗАПУСК

Первый тестовый запуск настроенной конфигурации можно выполнить, просто запустив отредактированный файл BxDTO-from-svc.bat на выполнение. Появятся консольные окна по числу настроенных в bat-файле процессов. Если в этих окнах нет сообщений об ошибках, и если в административном интерфейсе магазина появился список подключенных ККМ - значит всё сработало правильно, можно переключить работу BxDTO в режим системной службы. Для этого необходимо остановить все запущенные процессы (закрыть консольные окна), установить службу BxDTO-svc (запустить "C:\Program Files (x86)\BxDTO\bin\install_svc.bat" в режиме Администатора) и запустить службу BxDTO-svc из диспетчера служб Windows. Запустятся все те же процессы, которые настроены в BxDTO-from-svc.bat, но в режиме служб - без видимых окон. Служба по умолчанию устанавливается в режиме "ручной запуск". Если необходимо, чтобы BxDTO запускался при старте Windows, необходимо настроить режим запуска BxDTO-svc в диспетчере служб Windows. Под Linux для установки службы выполнить в консоли:

systemctl enable bxdto.service
systemctl start bxdto.service


МОНИТОРИНГ

Журналы работы служб BxDTO ведутся в каталоге "C:\ProgramData\Bitrix\BxDTO\1.0" в подкаталоге log, там же в подкаталоге db или db/<очередь> находятся БД очередей. При запуске BxDTO не-службой и не-администратором в каталоге установки по умолчанию "C:\Program Files (x86)\BxDTO" (недоступном для записи без повышения полномочий), журналы работы ведутся в каталоге "C:\Users\<User>\AppData\Local\VirtualStore\Program Files (x86)\BxDTO\bin\log" либо "C:\Users\<User>\AppData\Roaming\Bitrix\BxDTO\1.0\log".

Можно указать BxDTO вести логи и создавать БД в любом другом каталоге - для этого выбранный каталог должен быть текущим при запуске процессов BxDTO (добавить строку и записать команду
cd "путь\к\каталогу"
в bat-файле перед строкой start BxDTO). BxDTO сначала пытается создавать свои файлы в текущем каталоге, и только при невозможности этого из-за ограничения прав доступа переключается на "C:\ProgramData\Bitrix\BxDTO\1.0" (служба) или "C:\Users\<User>\AppData\Roaming\Bitrix\BxDTO\1.0\log" (консольный запуск).

Журналы запуска службы bxdto.service под Linux можно получить командой journalctl -u bxdto.service. После запуска службы процессы BxDTO ведут журналы в каталоге /log, если перед запуском не установлен другой текущий каталог. БД очередей в каталоге /db.

Журналы работы драйверов ДККТ10 ведутся в каталоге "C:\Windows\System32\config\systemprofile\AppData\Roaming\ATOL\drivers10\logs\" (либо "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\ATOL\drivers10\logs\" в 32-битном варианте) при запуске BxDTO службой либо в "C:\Users\<User>\AppData\Roaming\ATOL\drivers10\logs\" при запуске не-службой.

Журналы работы службы "Ethernet over USB" (EoU) ведутся в каталоге "C:\ProgramData\ATOL\EoU\logs". Под Linux - в /var/log/EoU.

Со стороны сервера магазина работоспособность конфигурации определяется по списку подключенных ККМ (автоматически заполняемому по результатам получения данных от BxDTO) в административном разделе. 

Если ККМ зарегистрирована в ФНС и настроена на отправку данных в ОФД, то состояние ККМ будет также отображаться на сервере ОФД. ККМ связывается с ОФД самостоятельно, без участия BxDTO, настройка сервера ОФД производится программой "Тест драйверов".

Если ККМ поддерживает печать на чековой ленте, и если указана опция --print в worker-процессе этой ККМ, то все полученные чеки должны распечатываться. Без опции --print чеки записываются во внутренний ФН в ККМ и визуально их контролировать можно по сайту магазина (где по обработанным чекам должны появляться правильные данные для QR-кодов, если ККМ фискализирована), по сайту ОФД, а также копии чеков будут отправляться на Email покупателей, если они указывались при оформлении покупки. Если Email не указывался, то чек будет напечатан независимо от опции --print.

В версии 1.1.17 добавлена опция --watchdog. Dispatcher и worker с этой опцией будут обновлять wd в своих циклах, а служба BxDTO-svc мониторить их и останавливаться в случае, если один или оба wd устарели (не обновляются больше 2 минут). Если в диспетчере служб Windows настроить BxDTO-svc на автоматический перезапуск при сбоях (вкладка "Восстановление" в свойствах службы), то при аварийных завершениях или зависаниях dispatcher'а или worker'а служба BxDTO-svc будет перезапускаться и перезапускать BxDTO-from-svc.bat.


СОВМЕСТНОЕ ИСПОЛЬЗОВАНИЕ BxDTO И ДРУГИХ ККТ-ПРОГРАММ

Worker-процесс BxDTO блокирует COM-порт, через который он взаимодействует с кассой, даже при отсутствии чеков/отчетов проверяя статус кассы для отправки его на сервер раз в минуту. Поэтому другие программы, которые могут работать c этой ККМ (1С, "Тест драйверов устройств печати" АТОЛ), не смогут работать одновременно с BxDTO - потребуется временно остановить BxDTO. И наоборот - если у вас запущен и подключен к ККМ "Тест драйверов", то BxDTO при запуске будет отправлять на сервер статус "порт занят", и онлайн-магазин не будет отправлять чеки на эту ККМ.

Также обратите внимание, что служба ATOL EoU ("Ethernet over USB") использует другой COM-порт из двух виртуальных COM-портов, создаваемых при подключении ККМ по USB - не тот порт, который использует BxDTO для управления ККМ. Поэтому между EoU и BxDTO конфликтов по портам не будет.

Если ККМ подключается к интернету не через USB+EoU, а через собственный Ethernet-порт, то одновременно использовать ККМ из нескольких программ всё равно не получится, так как на уровне драйверов DTO поддерживается только одно TCP-подключение к ККМ.


ОТКРЫТИЕ СМЕН И Z-ОТЧЕТЫ

BxDTO будет автоматически открывать смену и повторять печать чека, если при попытке печати чека ККМ сообщает о том, что смена закрыта. Также BxDTO автоматически закрывает текущую смену и затем открывает новую смену и печатает чек, если при попытке печати чека ККМ сообщает о "превышении смены" (если с момента открытия смены прошло больше 24 часов). При автоматическом закрытии смены печатается Z-отчет. При закрытой смене печать Z-отчетов невозможна - ККМ вернёт ошибку, и соответственно этот отчет на сайте получит статус ошибки.


ТЕХПОДДЕРЖКА

https://www.1c-bitrix.ru/support/
