Интеграция с кассовыми аппаратами

{toc:maxLevel=3}

h1. Схема взаимодействия биллинга с кассовым аппаратом

У кассира на рабочем компьютере должно быть запущено специальное приложение (tray_proxy). Биллинг, при авторизации кассира, запоминает его ip адрес и далее все команды для ККМ отправляются на этот ip адрес и обрабатывается приложением tray_proxy.
{INFO}
По умолчанию при печати чека для *наличной* оплаты биллинг отправляет команды на печать только 1 чека. В случае, если необходимо распечатать повторно тот же самый чек и отдать абоненту - используйте опцию *Повторить последний документ* на вкладке ККМ
{INFO}

h1. Операции с кассовым аппаратом

!ATOL2.png|border=0,width=400!

Доступны операции:
* Отчёт с гашением
* Отчёт без гашения
* Запустить ККМ
* Открыть смену
* Повтрорить последний документ
* Внесение средств - корректировка содержимого кассы, чтобы счетчик ККМ совпадал с фактическим количеством наличных денег в кассе, не добавляет средства на счёт абонента;
* Выемка средств - корректировка содержимого кассы, аналогично "Внесению средств";
* Проверка связи
* Получить ID терминала
* Закрыть день

h1. Установка и настройка

Версия драйвера АТОЛ должна быть не ниже 10.10.6.0.
{INFO}


h3. tray_proxy под Windows (XP, 7, 10)

Для работы необходимо:
* *Python 2.7* [Сайт|https://www.python.org/downloads/] (прямая ссылка на 32-битный инсталлятор: [python-2.7.10.msi|https://www.python.org/ftp/python/2.7.10/python-2.7.10.msi])
* *PyGTK 2.24* [Сайт|http://www.pygtk.org/downloads.html] (прямая ссылка на 32-битный инсталлятор: [pygtk-all-in-one-2.24.2.win32-py2.7.msi|http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.24/pygtk-all-in-one-2.24.2.win32-py2.7.msi])
* *PySerial 2.7* [Сайт|https://pythonhosted.org/pyserial/] (прямая ссылка на 32-битный инсталлятор: [pyserial-2.7.win32.exe|https://pypi.python.org/packages/47/c9/7802e11ab388ad1539de716649add8bb8ca8bdff660364b3a404f79c27b7/pyserial-2.7.win32.exe#md5=21555387937eeb79126cde25abee4b35])
* *PyWin32 build 221* [Сайт|https://sourceforge.net/projects/pywin32/] (ссылка на 32-битный инсталлятор: [pywin32-221.win32-py2.7.exe|https://sourceforge.net/projects/pywin32/files/pywin32/Build%20221/pywin32-221.win32-py2.7.exe/download])
* *zope.interface 4.1.3* [Сайт|https://zopeinterface.readthedocs.io] (прямая ссылка на 32-битный инсталлятор: [zope.interface-4.1.3.win32-py2.7.exe|https://pypi.python.org/packages/49/5f/ed5ea875af4e802198d035efe985d341d9b50edddbc22b785d2ef4b9eb66/zope.interface-4.1.3.win32-py2.7.exe#md5=e0a5bbc762126157b63d0233e26cc751])
* *Twisted 15.4.0* [Сайт|http://twistedmatrix.com/trac/wiki/Downloads] (прямая ссылка на 32-битный инсталлятор: [Twisted-15.4.0.win32-py2.7.msi|https://files.pythonhosted.org/packages/32/d9/7b958e09a0666d5760389aec0c684dd9b2df857e3513ed4bd00a95fdbe5b/Twisted-15.4.0.win32-py2.7.msi])

h3. tray_proxy под Ubuntu, Debian

Для работы необходимо:

* *Python 2.7*: _apt install python2.7 python-pip python-dev build-essential_
* *PyGTK 2.24*: _apt install python-gtk2_
* Обновить *pip*: _pip install \--upgrade pip_
* *PySerial 2.7*: \_pip install pyserial==2.7
* *zope.interface 4.1.3*: _pip install zope.interface==4.1.3_
* *Twisted 15.4.0*: _pip install Twisted==15.4.0_

Скрипт установки:

{code}
#!/bin/bash
apt install python2.7 python-pip python-dev build-essential python-gtk2
pip install --upgrade pip
pip install pyserial==2.7 zope.interface==4.1.3 Twisted==15.4.0
{code}

h2. Настройка tray_proxy и ККМ

Откройте файл _settings.py_ и укажите параметры:

* *BILLING_IP* \- IP биллинга (команды будут приниматься только с этого ip)
* *DEVICE_TYPE* \- тип устройства: 0 - COM-порт, 1 - USB
* *DEVICE* \- порт, к которому подключен кассовый аппарат, например: 'COM3'
* *BAUDRATE* \- скорость соединения с портом, например: 115200
* *KKM* \- протокол работы
* *DEBUG* \- следует выставить "0", если запускаете двойным кликом по "main.pyw", или "1", если через командную строку.
* *AUTOSTART* \- следует выставить "1", если после запуска скрипта нужно сразу запускать веб-сервер и соединение с ККМ.
* *TAX* \- код ставки НДС. Возможные значения:
** 0 - без НДС
** 1 - НДС 0%
** 2 - НДС 10%
** 3 - НДС 18%
** 4 - НДС 10/110
** 5 - НДС 18/118
** 6 - НДС 20%
** 7 - НДС 20/120
** 8 - НДС 5%
** 9 - НДС 7%
** 10 - НДС 5/105
** 11 - НДС 7/107
** 12 - НДС 22%
** 13 - НДС 22/122

+Опционально+: возможность передать все настройки (их может быть много) в виде строки json
* *ATOL_SETTINGS* = параметры для ККМ, например:
{code}r'{"Port":"1"}'{code}

Далее можно запускать *main.pyw* двойным кликом или через консоль (для запуска могут потребоваться права администратора).
Под Ubuntu есть возможность запуска приложения через иконку *TrayProxy* (файл иконки *tray_proxy.desktop*)
Правый клик по иконке в системном трее, пункт "Start Server" запустит веб-сервер, который будет принимать запросы на печать чеков от биллинга.
Для этого нужно убедиться, что порт 8080 открыт на компьютере кассира.

h3. Настройки для ШТРИХ-М

Для работы с данными ККМ нужно установить "ШТРИХ-М: Драйвер ККТ", скачать который можно по ссылке [https://www.shtrih-m.ru/support/download/] , и настроить взаимодействие с ККМ в драйвере.

В файлер settings.py укажите:

* *KKM* \- 'SHTRIH_COM'
* *DEVICE* \- 0, где 0 - номер устройства в драйвере

h3. Настройки для ПИРИТ

Сайт производителя аппарата: [http://www.crystals.ru/fiskalnyj-registrator]


Работа проверялась на аппарате *ПИРИТ ФР01К*

Каких-либо специфичных настроек интеграция с ПИРИТ не имеет.

Теоретически, поддерживаются все устройства, работающие по протоколу ПИРИТ.

h3. Настройка кассового аппарата АТОЛ

Сайт производителя аппарата: [http://www.atol.ru/products/kkt/]
Описание протокола:
* [Описание протокола АТОЛ версии 3.1|Интеграция с кассовыми аппаратами^Протокол_ККТ_3.1.pdf]
* [Описание протокола АТОЛ версии 3.0|Интеграция с кассовыми аппаратами^Протокол_ККТ_3.0.pdf]
* [Описание протокола АТОЛ версии 2.4|Интеграция с кассовыми аппаратами^Protokol_KKM_2.4_040614.pdf]

h4. Протокол АТОЛ ККТ 3.1

По данному протоколу осуществляется поддержка 54-ФЗ аппаратами Атол с ФФД 1.0.5. Работа проверялась на аппарате *АТОЛ 30Ф*

Как настроить:
# Для работы нужен драйвер АТОЛ версии 10 или выше, его можно скачать в [центре загрузки АТОЛ|http://fs.atol.ru/SitePages/Центр загрузки.aspx] в разделе "*Контрольно-кассовая техника*".
Прямая ссылка на версию драйвера 10.10.6.0: [https://fs.atol.ru/_layouts/15/atol.templates/Handlers/FileHandler.ashx?guid=32a1c76d-1166-4536-b8df-d9cc244f3ff2&webUrl=]
{note}Если используется Windows - обязательно устанавливайте 32-битную версию (архив/версия/installer/exe/KKT10-версия-windows32-setup.exe).{note}
{note}Устанавливать драйвер в ОС Windows необходимо в папку: C:\Program Files\ATOL{note}
# После скачивания архива скопируйте *libfptr10.py* (файл архив/версия/wrappers/python/) в папку с TrayProxy.
# Укажите в _settings.py_:
#* *KKM* \- ATOL3
# Дополнительные опции для TrayProxy: возможность передать все настройки (их может быть много) в виде строки json
#* *ATOL_SETTINGS* \- параметры для ККМ, например:
{code}r'{"Port":"1"}'{code}

Если настройки не подошли, адаптер попытается вызвать окно настроек драйвера. Если после этого соединение удастся - успешные настройки будут записаны в лог.

h4. Протокол АТОЛ ККТ 2.4

Работа проверялась на аппаратах *Fprint-03K* и *Fprint-22K*
{info}
Внимание: У названия ККТ Fprint в конце должна быть буква *K*. Например в названии FPrint-55K. Оборудование FPrint-55 (без буквы *К*) является принтером а не ККТ и не поддерживается для интеграции с биллингом
{info}
Теоретически, поддерживаются ККТ FPrint-55K, FPrint-22K, FPrint-11ПТК и FPrint-77ПТК, поддерживающие _протокол Атол версии 2.4 с включенным режимом совместимости 1.0_
Если Ваше устройство работает по протоколу версии 3, то переключить его на протокол 2 версии можно через Сервисный режим.

h4. Режим совместимости для протокола 2.4 и ФФД 1.0

Для оборудования с версией протокола 3\+ необходимо включить режим совместимости через драйвер идущий в поставке
!kkm_sec_kod.png|border=0,width=450!

На 4 шаге установите значения:
* Таблица 2 Ряд 1 Поле 109
* Значение установите 001

h3. Verifone vx820. Безналичная оплата с терминалов

Для того, чтобы биллинг мог отправлять команды на терминал Verifone для списания конкретной суммы с абонентов, необходимо провести следующую настройку:

# TrayProxy
{code}POS = 'PILOTNT'
POS_PATH = r'C:\sc552'{code}
#* *POS* \- включение поддержки POS-терминала, PILOTNT -- имя адаптера (в данный момент единственный)
#* *POS_PATH* \- путь где искать файл _pilot_nt.dll_. Чаще всего ПО Сбербанка располагается в папке _C:\sc552_
\\
\\
# Перейти на вкладку *Платежные системы - Настройки веб-кассы* и выставить опцию *ИСПОЛЬЗОВАТЬ POS-ТЕРМИНАЛ*
!kassa1.png|border=0,width=760!
\\
\\
# Для того, чтобы можно было отправить команды на терминал, необходимо перейти в меню *Веб-касса*, найти нужного абонента и добавить *Безналичный* приход, выставив данную опцию.
!kassa2.png|border=0,width=370!
\\
\\
# После добавления прихода, он будет отображен у абонента. Для того, чтобы данную сумму списать с карты абонента, необходимо рядом с платежом выбрать пункт *Оплатить картой*
!kassa3.png|border=0,width=230!

После этого команды будут отправлены на терминал и абоненту будет предложено вставить/приложить карту.
Как только списание завершится, биллинг автоматически отправит команды на печать чека.

{warning}
Внимание: Опция *Оплатить картой* будет доступна только для безналичных платежей\!
{warning}

h2. Настройка биллинга

В [настройках веб-кассы|CarbonBilling:Веб-интерфейс кассира] в поле "*ККМ (PIRIT, ATOL И Т.П.)*" нужно указать протокол:
{info} Для всех новых инсталяций и инсталяций на Linux используется Атол версии 3{info}
* +Оставьте пустым+ для _АТОЛ версии 3_
* *ATOL* \- для АТОЛ версий 1 и 2
* *SHTRIH_COM* \- для ШТРИХ-М
* *PIRIT* \- для ПИРИТ

У АТОЛ есть пароли оператора и смены режима:
* *ККМ ПАРОЛЬ ДОСТУПА* \- по умолчанию "0"
* *ККМ ПАРОЛЬ СМЕНЫ РЕЖИМА* \- по умолчанию "30".

h1. Решение проблем с TrayProxy

Для работы с ККМ необходимо:

# Перейти на вкладку "Веб - касса" из меню основной платформы
!BASE.png|border=0,width=100!
\\
\\
# Выбрать вкладку "ККМ"
!KKT.png|border=0,width=350!
\\
\\
# В открывшемся меню нажать на кнопку "Запустить ККМ"

Если биллинг выдаст ошибку необходимо:
# Открыть файл *settings.py* и выставить в поле *"DEBUG"* значение *"1"*
# Запустить файл *main.pyw* из командной строки с помощью _python_.
# Для запуска из командной строки необходимо перейти в каталог с установленным питоном и выполнить команду *python 'путь до файла main.pyw"*, напирмер:
{code}python C:\tray_proxy\main.pyw{code}
# После этого откроется окно с подробным логом
# Ещё раз нажмите кнопку *"Запустить ККМ"* и увидите какую именно ошибку выдает tray_proxy

h2. Нет связи с ККМ

Убедитесь что с биллинга доступен порт 8080 компьютера оператора, на котором запущен TrayProxy.
Проверите открыт ли порт 8080:
{info}
root@billing # telnet 192.168.0.0 8080
Trying 192.168.0.0...
{info}

Trying означает, что порт закрыт. При установлении связи появится статус "Connected".
Если порт закрыт, установите необходимые правила файрвола, или отключите брандмауэр.

{info}
Reject host 192.168.0.0
{info}
В логе trayproxy.log ошибка "reject" также означает отсутствие связи между биллингом и ПК, на котором установлена касса.

Если компьютер находится за NAT, пробросьте порт на маршрутизаторе.
{info}
В момент нажатии кнопки *Открыть смену* биллинг пытается отправить команду на tray_proxy, который находится на компьютере оператора, поэтому, если у биллинга нет доступа до компьютера оператора - связи не будет.
{info}

h2. Некорректный ответ API от ККМ

Возможно указаны неверные пароли. Необходимо перейти на вкладку *Платежные системы - Настройки веб-кассы* и поменять значения 30 и 0 у полей *ККМ ПАРОЛЬ ДОСТУПА* и *ККМ ПАРОЛЬ СМЕНЫ РЕЖИМА*

h2. Произошла ошибка api: Неверная длина

У ККМ есть ограничение длины строки, у некоторых моделей это значение немного отличается. По умолчанию задано 48 символов. Ошибка "Произошла ошибка api: Неверная длина" означает, что для Вашего аппарата необходимо указать другое значение этого параметра. Изменить можно с помощью файла /app/asr_billing/cfg/kkm_atol_webcash.json , записав туда:
{code}
{"stringMax": 32}
{code}
Вместо "32" необходимо указать длину строки для Вашего аппарата.

h2. Выполняется другая команда

Если биллинг выдает ошибку "Выполняется другая команда" - скорее всего драйвер не может запуститься, либо не закрыли диалог настроек АТОЛ.

h2. Драйвер не готов

Если Вы используете Windows и АТОЛ версии 3, убедитесь что установлен 32-битный драйвер +даже если ОС 64-битная+ \- это можно посмотреть в оснастке "[Установка и удаление программ|https://support.microsoft.com/ru-ru/help/4028054/windows-10-repair-or-remove-programs]"

h2. Если все выше не помогло, что дать техподдержке чтобы мне помогли?

# Включите _DEBUG_ в settings.py: *DEBUG = 1*
# Запустите TrayProxy
# Выполните команду с биллинга
# Если в интерфейсе кассы появилась ошибка, сделайте скриншот
# Создайте заявку и приложите к ней:
#* Файл _debug.log_
#* Файл настроек _settings.py_
#* Скриншот ошибки