Руководство программиста - arMax :: платежные решения

Общество с ограниченной ответственностью «ФЭР ПЭЙ»
УТВЕРЖДАЮ
Генеральный директор
ООО «ФЭР ПЭЙ»
Чухлеб О.Ф.
Программно-технический комплекс
FAIR BOX-01К
РУКОВОДСТВО ПРОГРАММИСТА
2009
Содержание
1. Общие положения................................................................................................3
2. Нижний уровень..................................................................................................4
2.1 Структура блока команды и ответа
4
2.2 Схема обмена данными
6
2.3 Ошибки при передаче
7
3. Верхний уровень..................................................................................................8
3.1 Общие положения
8
3.2 Поддерживаемые команды
8
3.2 Ответ по умолчанию
9
3.3 Запрос состояния ПТК
9
3.5 Работа с купюроприемником
12
3.6 Команды регистрации
13
3.7 Команды отчетов
14
3.8 Сервисные команды
16
3.9 Команды работы с сохраненным чеком
16
3.10 Инкассация
17
Приложение А........................................................................................................18
2
1. Общие положения
Программно-технический комплекс
работы
в
составе
платежного
FAIR BOX-01K предназначен для
терминала.
Обмен
данными
между
компьютером платёжного терминала и ПТК ведётся по интерфейсу RS – 232
со скоростью 115200 бод и с физическим кадром:
• 1 стартовый бит;
• 8 битов данных;
• 1 стоповый бит;
• без проверки на четность;
• без управления потоком;
• 3 линии (TXD, RXD, GND).
Документ состоит из двух основных частей: «Нижний уровень» и
«Верхний уровень».
Под командой понимается посылка, состоящая из кода команды и
данных (они могут отсутствовать), которые определяют тип действия для
ПТК. На каждую команду ПТК присылает ответ, содержащий код ошибки и
данные (могут отсутствовать) в зависимости от команды.
Все команды и ответы передаются по единому протоколу нижнего уровня,
который обеспечивает
достоверность
передачи
данных с
помощью
механизма контрольных сумм и повторов. Таким образом, в разделе
«Нижний уровень» описан общий для всех команд и ответов алгоритм их
передачи и приема.
В
разделе «Верхний
уровень»
описаны
конкретные
коды
команд,
передаваемые в них данные и форматы ответов на команды, а также
возможные коды ошибок и их описание.
3
2. Нижний уровень
Управляющие символы протокола
Символ
Расшифровка
Код
ENQ
Запрос
05H
ACK
Подтверждение
06H
STX
Начало текста
02H
ETX
Конец текста
03H
EOT
Конец передачи
04H
NAK
Отрицание
15H
DLE
Экранирование управляющих символов
10H
2.1 Структура блока команды и ответа
STX <data[N]> ETX <CRC>
STX – флаг начала блока команды или ответа
<data[N]> – посылаемые данные (N <= 4096 байт)
ETX – флаг конца блока команды или ответа
<CRC> – байт контрольной суммы
Байты
DLE и ETX передаются как последовательность двух байт: 10h
как <DLE DLE>, 03h
как <DLE ETX>. Такая
операция далее будет
называться маскировкой. Все остальные байты (даже равные остальным
управляющим символам) передаются как один байт.
Контрольная сумма вычисляется как побайтное исключающее ИЛИ (XOR)
по всем символам блока, включая ETX, но исключая STX.
В качестве передатчика выступает управляющая программа платежного
терминала, в качестве приемника — ПТК.
4
Используемые таймауты:
T1
T2
T3
T4
T5
T6
T7
T8
0,5 сек
2 сек
0,5 сек
0,5 сек
10* сек
0,5 сек
0,5 сек
1 сек
* – для некоторых команд значение Т5 указано в таблице.
Команда (HEX) Таймаут в сек. Название команды
E6
60
Закрыть чек
F2
120
Снять z-отчет
F3
120
Снять x-отчет
5
2.2 Схема обмена данными
При нормальной работе схема обмена выглядит следующим образом:
Управляющая программа терминала ПТК
(УПТ)
1. Запрос готовности к сеансу связи 2. ПТК готов к сеансу связи,
ENQ
сообщает об этом УПТ посылкой
сигнала ACK
3. УПТ посылает кадры данных
STX, data[N], ETX, <CRC>
(последовательность не может быть
изменена)
4. ПТК получает все кадры данных,
вычисляет контрольную сумму и,
если она совпала с переданной,
посылает подтверждение получения
сигналом ACK
5. EOT (завершение передачи)
6. Запрос готовности к сеансу связи
ENQ
7. УПТ готов к сеансу связи, 8 ПТК посылает кадры данных
сообщает об этом ПТК посылкой
STX, data[N], ETX, <CRC>
сигнала ACK
(последовательность не может быть
изменена)
9. УПТ получает все кадры данных, 10. EOT (завершение передачи)
вычисляет контрольную сумму и,
если она совпала с переданной,
посылает подтверждение получения
сигналом ACK
6
2.3 Ошибки при передаче
1. Конфликтная ситуация: одновременно приходят запросы к сеансу связи
от УПТ и ПТК. Такая ситуация разрешается с помощью разных
интервалов ожидания Т7 и Т8.
2.
Нет ответа или неверный ответ на сигнал ENQ. Если по истечении
таймаута Т1 не получен ответ, сигнал ENQ повторяется. Если после 5
попыток ответ не получен, посылается сигнал завершения передачи
EOT. Если сеанс связи не возможен, на запрос ENQ приходит ответ
NAK.
3.
Ошибка в блоке данных. В случае, если вычисленная контрольная
сумма не совпадает с переданной, посылается сигнал отказа приема
NAK. Необходимо повторить кадры данных (см. п. 3 и п.8 схемы
обмена). Если ошибка в блоке данных повторяется более 10 раз,
посылается сигнал завершения передачи EOT и одна из сторон
считается нерабочей.
4.
Нет передачи EOT. Если после посылки сигнала подтверждения ACK
нет сигнала EOT в течение времени Т4, считать, что EOT получен и
завершать передачу.
5.
Нет ответа на команду: если в течение времени Т5 УПТ не получает
сигнала начала ответа ENQ, команда считается невыполненной.
7
3. Верхний уровень
3.1 Общие положения
Любая команда предваряется посылкой пароля на связь (4 цифры, 2 байта
BCD)
Все строки посылаются и принимаются в кодировке cp866 .
Все денежные величины — целые числа, указанные в минимальной
денежной единице (копейка).
Количество — целое число, указанное в граммах. При этом количество 1
единица товара (услуги) считается равной 1 килограмму (соответствует
1000).
Доступ к отчетам из ФП и ЭКЛЗ возможен только с помощью клавиатуры. В
случае неверного пароля второй байт ответа на команду будет равен 0×02, т.е.
придет ответ 'U' 0×02 0×00
Если команда вернула в состоянии 1, т.е. выполнилась с ошибкой, нужно дать
команду «получить текст последней ошибки», чтобы показать ее оператору.
3.2 Поддерживаемые команды
Код команды Команда
(HEX)
B0
Получить дату-время ПТК
B1
Установить дату
B2
Установить время
B3
Получить количество свободных ячеек для записи zотчетов
B4
Распечатать все сохраненные z-отчеты
B5
Получить информацию обо всех инкассациях
Е0
Текст последней ошибки
E3
Открыть чек
E4
Регистрация продажи
E5
Аннуляция чека
E6
Закрыть чек
8
E7
Прочесть статус купюроприемника
E8
Принять купюру
E9
Вернуть купюру
F0
Принудительно завершить цикл
F1
Получить состояние ПТК в момент платежа
F2
Снять z-отчет
F3
Снять x-отчет
F4
Запрос лога ПТК
F5
Запрос файла
F6
Открыть сохраненный чек
F7
Проверить сохраненные сессии
F8
Инкассация
F9
Получить информацию о последней инкассации
D8
Получить статус ПТК (при старте)
D9
Получить регистры ПТК
3.2 Ответ по умолчанию
Большинство команд возвращает ответ вида:
• 'U' - 1 байт, символ ответа на команду,
• 0|1 — 1 байт, отчет о выполнении команды. 0 — команда выполнилась
без ошибок, 1 — команда выполнилась с ошибками.
•
0 – конец посылки.
Если команда выполнилась без ошибок, за вторым байтом может следовать
результат выполнения команды. Если команда выполнилась с ошибкой, УПТ
может запросить текст последней ошибки — команда E0.
3.3 Запрос состояния ПТК
При старте УПТ должна запросить статус ПТК.
Формат команды: 0xD8
Ответ: 'U', <состояние(1)>, <номер последней регистрации ФП(2BCD>,
<номер последней регистрации ЭКЛЗ(2BCD)>, <номер последнего сменного
9
отчета(2BCD)>,
последнего
<день
последнего
сменного
сменного
отчета(1BCD)>,
<год
отчета(1BCD)>,
последнего
<месяц
сменного
отчета(1BCD)>, <рег. номер ЭКЛЗ(10CHAR)>, <модель кассы(30CHAR)>,
<заводской номер(8CHAR)>, <рег. номер(10CHAR)>, <ИНН(13CHAR)>,
<режим работы(2BCD)>, <номер терминала(5BCD>, <флаги(5BCD)>
Возможные режимы ПТК:
0×0001 - выбор
0×0002 - регистрация
0×0004 - Z-отчет
0×0008 - программирование
0×0010 - доступ к ФП
0×0020 - доступ к ЭКЛЗ
0×0040 - сервисный режим
0×0080 - критическая ошибка
0×0100 - прием денег
10
Флаги ПТК:
Флаг
Битовая Описание
маска
(HEX)
SC_FISCALIZED
1
ПТК фискализирован
SC_FM_ERROR
2
Ошибка ФП
SC_FM_IS_FULL
4
ФП заполнена
SC_ECTS_IS_ACTIVE
8
ЭКЛЗ активирована
SC_ECTS_ERROR
10
Ошибка ЭКЛЗ
SC_ECTS_IS_FULL
20
ЭКЛЗ заполнена
SC_ECTS_EXISTS
40
ЭКЛЗ присутствует
SC_ECTS_VS_FM
80
Несовпадение смен в ЭКЛЗ и ФП
SC_ECTS_IS_ALIEN
100
Чужая ЭКЛЗ
SC_ECTS_VS_KKM_BY_DT 200
Несовпадение дат в ПТК и ЭКЛЗ
SC_ECTS_VS_KKM_BY_RE 400
LAY
Несовпадение смен в ПТК и
ЭКЛЗ
SC_ECTS_VS_KKM_BY_SU 800
MM
Несовпадение сумм в ПТК и
ЭКЛЗ
SC_FM_VS_KKM_BY_DT
Несовпадение дат в ПТК и ФП
1000
SC_FM_VS_KKM_BY_SUM 2000
M
Несовпадение сумм в ПТК и ФП
SC_PRINTER_ERROR
Ошибка принтера
4000
SC_FM_ACCESS_BLOCKED 8000
Неправильный пароль
налогового инспектора
SC_NEED_CLOSE_RELAY
10000
Нужно закрыть смену
SC_CRITICAL_DT_ERROR
20000
Критическая ошибка даты
SC_Z_OPEN
10000000
Z-отчет открыт
SC_Z_ECTS_NOT_CLOSED
20000000
Смена в ЭКЛЗ еще не закрыта
SC_Z_FM_NOT_CLOSED
40000000
Смена в ФП еще не закрыта
SC_Z_KPK_WAS_NOT_PRIN 80000000 Не успели напечатать КПК
TED
11
3.4 Запрос регистров ПТК
Формат команды: 0xD9
Ответ: 'U', 0, <текущая смена(3BCD)>, <последняя закрытая смена(3BCD)>,
<дата открытия текущей смены(ДД.ММ.ГГ,3BCD)>, дата закрытия последней
закрытой смены(ДД.ММ.ГГ,3BCD)>, <состояние текущей смены(1)>, <номер
последнего документа(3BCD)>, <номер последнего чека(3BCD)>, <гросситог(10BCD)>
Состояние текущей смены: 0 - закрыта, 1 - открыта
3.5 Работа с купюроприемником
0xE7 — Запрос статуса купюроприемника
Команда выполняется только при открытом чеке
Формат команды: 0xE7
Ответ: 'U', 0 <количество записей (1 байт)>, <записи (1 байт каждая)>
Все состояния купюроприемника складываются в буфер, поэтому если
команда запроса статуса поступает редко (реже, чем раз в 100 мсек) в ответ
приходит несколько записей.
Ответы купюроприемника:
0×00 - сбой мотора;
0×01 - ошибка CRC;
0×02 - замятие;
0×03 - изъятие купюры;
0×04 - стекер открыт;
0×05 - сбой сенсора;
0×06 - выключен;
0×07 - попытка обмана купюроприемника;
0×08 - ошибка;
0×09 - возвращает купюру;
0x0A - не распознал;
0x0B - ждем;
0x0C - выключен (inhibit);
12
0x0D - вернул купюру;
0x0E - принимает;
0x0F - принял 10 рублей;
0×10 - принял 50 рублей;
0×11 - принял 100 рублей;
0×12 - принял 500 рублей;
0×13 - принял 1000 рублей;
0×14 - принял 5000 рублей;
0×15 - купюра уложена;
0×16 - сбой купюроприемника;
0×17 - питание 1;
0×18 - питание 2;
0×19 - неправильный ответ;
0x1A - буфер купюроприемника пустой.
Получив ответ на запрос статуса, УПТ отправляет команду «Принять
купюру» или команду «Вернуть купюру».
0xE8 — Принять купюру
Команда выполняется только при открытом чеке
Формат команды: 0xE8 <итоговая комиссия с учётом этой ещё не принятой
купюры>
Ответ: стандартный
0xE9 — Вернуть купюру
Команда выполняется только при открытом чеке
Формат команды: 0xE9
Ответ: стандартный
3.6 Команды регистрации
0xE3 — Открыть чек
Формат команды: 0xE3 <таймаут в секундах(2BCD), id оператора(3BCD),
оператор (нуль-терминальная строка, cp866, не больше 40 байт), телефоны
службы поддержки (нуль-терминальная строка cp866, не более 80 байт)>
Ответ: стандартный
13
В команду передаётся id оператора по приёму платежей из базы терминала,
телефоны оператора и платежной системы и наименование оператора для
группировки платежей в отчете.
После открытия чека становятся доступными команды 0xE4, 0xE5, 0xE6,
0xE7, 0xE8, 0xE9. Остальные команды блокируются.
0xE4 — Регистрация продажи
Команда выполняется только при открытом чеке
Формат команды: 0xE4 <цена(5BCD), кол-во(5BCD), номер секции (1BCD),
наименование услуги(может быть многострочным, строки заканчиваются
символом LF, нуль-терминальная строка, не более 2КБайт) >
Ответ: стандартный
0xE5 — Аннуляция чека
Команда выполняется только при открытом чеке. Аннуляция возможна только
если после открытия чека не было команд «принять купюру».
Аннулирует открытый чек
Формат команды: 0xE5
Ответ: стандартный
0xE6 — Закрыть чек
Команда выполняется только при открытом чеке
Формат команды: 0xE6
Ответ: 'U', 0 <Номер документа(2BCD), дата и время: день(1BCD),
месяц(1BCD), год(1BCD), часы(1BCD), минуты(1BCD), секунды(1BCD),
итоговая сумма чека (5BCD), номер чека(2BCD)>
3.7 Команды отчетов
Сразу после команды отчета проверяется возможность снятия отчета и, если
его можно сформировать, выполняется посылку 0×55, 0×00 + 2BCD номера
будущего документа. Потом ПТК запрашивает сессию и посылает побайтово
файл отчета. Начало передачи 0×02, конец - немаскированный 0×03, потом
CRC. В случае если при формировании z-отчета произошел сбой,
14
и отчет записан в ЭКЛЗ, он распечатается при перезагрузке ПТК. Если не
был записан — нужно снять повторно.
Таймауты по отчетам - до 120 секунд
В содержимом отчета может встретиться последовательность символов 0x5E
0x6F 0x5E - признак фискализации
На команды отчетов приходят 2 ответа:
−
ответ возможности снятия отчета — 0х55, 0х00, <Номер отчета> (2
байта BCD). Следом передаётся текст отчёта в новый фрагмент данных
(завершается контрольной суммой).
−
ответ невозможности снятия отчета — 0х55, 0х01, 0x00
0xF2 - Снять Z-отчет
Формат команды:
0xF2 <куда снимать отчет (1BCD) (в буфер, на
принтер)>
0xF3 - Снять Х-отчет
Формат команды: 0xF3 <куда снимать отчет (1BCD) (в буфер, на
принтер)><тип отчета - 1BCD>
Типы Х-отчетов:
•
•
•
•
0 - суточный
1 - по секциям
2 - почасовой
3 - по услугам
Куда снимать отчет:
• 1 - на принтер
• 2 - в файл
0xB3 - Получить количество свободных ячеек для отложенных z-отчетов
- без параметров
Ответ: количество ячеек (1BCD)
Если количество ячеек равно нулю, то ПТК не может снимать z-отчеты
вообще. Нужно дать команду «распечатать все отложенные z-отчеты»
0xB4 - Распечатать все отложенные z-отчеты - без параметров
Ответ: по умолчанию. Внутри команды ошибки, возникшие во время печати,
не обрабатываются. Т.е. если отчеты есть и принтер на момент отправки
команды работает, ПТК начинает печатать. Если во время печати какого-то
15
отчета произойдет сбой принтера, то при устранении неисправности команду
нужно дать повторно, чтобы допечатать оставшиеся в буфере отчеты.
3.8 Сервисные команды
Запрос лога
Формат команды: 0xF4 <тип запроса (1 байт), количество строк (2BCD)
>
Тип запроса:
0 — получить последние n строк лога
На команду лога возможны 2 ответа:
−
лог получен — 0х55, 0х00, 0х00. Следом передаётся текст логов в
кодировке cp866 (завершается контрольной суммой).
−
ответ ошибки получения лога — 0х55, 0х01, 0х00.
Запрос файла
Формат команды: 0xF5 <имя файла (нуль-терминальная строка) >
На команду запроса файла возможны 2 ответа:
−
файл получен — 0х55, 0х00, 0х00. Следом передаётся содержимое
файла(завершается контрольной суммой).
−
Ошибка получения файла — 0х55, 0х01, 0х00.
3.9 Команды работы с сохраненным чеком
Сохраненный чек предназначен для восстановления работоспособности
ПТК в том случае, если произошло отключение питания или ошибка ПТК во
время приема платежа. В такой ситуации после устранения неисправности
требуется открыть сохраненный чек и выполнить регистрацию продажи.
Предварительно рекомендуется проверить сохраненные сессии на наличие
сохраненного чека.
0xF6 Открыть сохраненный чек - без параметров.
16
Ответ: по умолчанию.
В этом режиме доступны команды 0xE4, 0xE6, 0xF0
0xF7 Проверить, есть ли сохраненные сессии - без параметров.
Ответ: статус(1BCD).
Статус: 1 - сохраненные сессии есть (ПТК после сбоя), 0 - сохраненных
сессий нет. Если статус 1, в ответе передаются дополнительные параметры:
дата и время сессии (день 1BCD, месяц 1BCD, год 1BCD, часы 1BCD,
минуты 1BCD, секунды 1BCD), таймаут в секундах (2BCD), ID оператора
(3BCD), сумма (5BCD), комиссия (5BCD), записан ли чек в ЭКЛЗ(1 байт),
имя оператора (строка, cp866, не больше 40 символов).
Записан ли чек в ЭКЛЗ:
0 - не записан
1 - записан
Если в момент сохранения чека в ЭКЛЗ возникла ошибка, например, от
ЭКЛЗ ответ не получен, но физически информация записалась, после
перезагрузки ПТК самостоятельно восстановит чек и распечатает его.
3.10 Инкассация
0xF8 Инкассация - сумма (5BCD)
Ответ: по умолчанию
0xF9 Получить информацию о последней инкассации - без
параметров
Ответ: 0×55, <статус>, <инфо> Статус: 0 - информация прочитана, 1 ошибка. Инфо: нуль-терминальная строка в cp866, информация о последней
инкассации.
0xB5 Получить информацию обо всех инкассациях
Ответ: как на команду «получить файл»
Результат - строка cp866, в качестве разделителя строк используется
0×10.
17
Приложение А
Пример передачи числа в формате BCD
1.Пусть необходимо передать число 1234567 и длина посылки — 5 BCD.
2. Дополняем число до 10 разрядов (5 байт по 2 разряда в байте): 0001234567
3. Разбиваем последовательность на пары: 00 01 23 45 67.
4. Записываем каждую пару в байты: 00h 01h 23h 45h 67h.
5. Передаем байты, начиная с 00h, затем 01h, 23h, 45h и последним 67h.
18