FR Server (информация для программистов)

Назначение и схема работы

FRServer - это специальная программа для управления фискальным регистратором (ФР) и платёжным терминалом (ПТ) Сбербанка.

Появление данной программы связано с желанием запускать Домино в облаке (например, по rdp) и при этом управлять оборудованием, которое по rdp недоступно.

В типовой схеме ФР и ПТ подключаются к конкретному компьютеру, получают команды непосредственно от данного компьютера. Управление этими устройствами по rdp либо невозможно, либо очень сложно. Задача легко решается, если имеется посредник, который размещается рядом с ФР и ПТ, получает команды из Домино и передаёт эти команды в ФР и ПТ. Таким посредником и является FRServer.

FRServer получает команду от управляющей программы (Домино) и, в соответствии с полученной командой, обменивается информацией с фискальным регистратором (ФР) и платёжным терминалом Сбербанка. Далее FRServer передаёт результат выполнения команды в управляющую программу (Домино).

FRServer получает команды одним из двух способов:

Номер порта должен задаваться в конфигурационном файле FRServer.ini, находящемся в рабочей директории FRServer, таким образом:

[System]
Port=3800

Каталог указывается в конфигурационном файле

[System]

FileMask=C:\FRServer\files\*.*

Управляющая программа создаёт файл с командой в указанном каталоге. FRServer находит файл, обрабатывает команду и создаёт файл ответа в подкаталоге OUT указанного каталога.

 

Настройка

  1. Перед запуском FRServer следует настроить ФР через его собственный драйвер и проверить работоспособность. Для проверки можно запустить FRServer с параметром /SETTING. 
  2. В рабочей директории FRServer должен находиться специальный файл сертификата, содержащий список разрешённых URL. При получении посылки FRServer анализирует URL отправителя и обрабатывает полученные данные только в том случае, если URL разрешён.

 

Формат посылок

Посылка для FRServer (тип посылки POST) всегда содержит один параметр:

CMD=<NNN>

NNN – это команда.

Ответ FRServer-а имеет вид:

<?xml version="1.0" encoding="windows-1251"?>
<root>
<Response Result="" Description=""/>
</root>

Тег “Result” имеет значение “OK” или “Error”. В случае Error, тег Description содержит описание ошибки.

Для команды FR_GETREADY, в случае Result= OK, тег Description содержит данные о состоянии смены, состоянии текущего чека, номере смены и номере чека.

Команды

Команды

Список команд

Команды для ФР

Команда

Назначение

Доп. параметры

FR_GETREADY

Запрос готовности ФР к работе

 

FR_GETSERIALNUM

Запрос серийного номера ФР

 

FR_GETSESSIONSTATUS

Запрос статуса смены ФР

 

FR_REGISTEROPERATOR

Регистрация оператора ФР

+

FR_OPENSESSION

Открытие смены

+

FR_CLOSESESSION

Закрытие смены

+

FR_PRINTCHECK

Печать чека продажи/возврата

+

FR_CANCELCHECK

Отмена чека

 

FR_CHECKKM

Проверка достоверности марки

+

FR_INCASH

Внесение

+

FR_OUTCASH

Инкассация

+

FR_PRINTXREPORT

Печать X-отчета

 

FR_PRINTTEXT или FR_PRINTFILE

Печать текстового буфера 

+

FR_PRINTQRCODE

Печать QR-кода

+

FR_CUT

Отрезка чека

 

FR_OPENDRW

Открытие ящика

 

Команды с параметрами

Команда

Параметры

Значение

FR_REGISTEROPERATOR

 

CODEPAGE

Кодировка текста: UTF8, если текст не в кодировке ANSI. Может быть опущен (по умолчанию используется ANSI).

USER_CODE

Код оператора (целое, 1 – 30). Обязателен для ФР «Штрих» и «Атол».

USER_NAME

Имя оператора

USER_INN

ИНН оператора (может отсутствовать)

FR_OPENSESSION

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.
Регистр не имеет значения (как для имени параметра, так и для его значения).

FR_CLOSESESSION

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.

FR_PRINTCHECK

CODEPAGE

Кодировка текста: UTF8, если текст не в кодировке ANSI. Может быть опущен (по умолчанию используется ANSI).

 

USER_CODE

Код оператора (целое, 1 – 30). Обязателен для ФР «Штрих» и «Атол».

 

USER_NAME

Имя оператора

 

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.

 

DATA

Буфер данных в формате xml

FR_PRINTQRCODE

DATA

Текстовая строка для печати

FR_CHECKKM

KM

CHECK_TYPE

Считанный код марки (без преобразований)
Тип чека, в котором предполагается участие маркированного товара (SALE или RETURN).

Строки разделяются символами \r\n (x0d x0a). Символ <B> в тексте означают жирную печать следующего за ним текста (до CRLF). Символы <QR> в тексте означают печать следующего за ними текста (до CRLF) в виде QR-кода.

Любая команда ФР может содержать данные регистрации оператора. Если такие данные переданы с командой, то будет выполнена попытка регистрации. Отрицательный результат регистрации на выполнение команды не влияет.

Имя оператора может потребоваться для печати в чеках, X- и Z-отчётах.
Для ФР «Штрих» и «Атол»: код оператора (1 – 30) – это значение из таблицы кассиров ФР. На чеке печатается имя кассира из этой таблицы. Переданное имя сохраняется в таблице.

Команды для ПТ

Команда

Назначение

Доп. параметры

PAYMENT_SALE

Оплата продажи

+

PAYMENT_RETURN

Возврат продажи

+

PAYMENT_ROLLBACK

Сторно транзакции

+

PAYMENT_CLOSE

Сверка (закрытие смены на терминале)

 

Команды с параметрами

Команда

Параметры

Значение

PAYMENT_SALE

SUM

Сумма оплаты

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.
Регистр не имеет значения (как для имени параметра, так и для его значения).

PAYMENT_RETURN

TRANSACTION_ID

ID оригинальной транзакции

SUM

Сумма оплаты

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.

PAYMENT_ROLLBACK

TRANSACTION_ID

ID оригинальной транзакции

SUM

Сумма оплаты

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.

PAYMENT_CLOSE

ReportElectronically

Признак «Без печати на чековую ленту». Возможные значения:
1, Y, yes, true – печать на чековую ленту не выполняется.
Другие или отсутствие – чек печатается.

Команды

Команды для ФР

Запрос готовности ФР к работе (команда FR_GETREADY)

Без параметров.

Формат ответа:

<?xml version="1.0" encoding="windows-1251"?>

<root>

   <Response Result="OK" Description="ReadyStatus:1, SessionStatus:1, SessionNO:123, CheckStatus:0, CheckNO:1” />

</root>

Если Result=Error, то тег Description содержит описание ошибки.

Если Result= OK, то тег Description содержит:

Запрос серийного номера ФР (команда FR_GETSERIALNUM)

Без параметров.

Формат ответа:

<?xml version="1.0" encoding="windows-1251"?>

<root>

   <Response Result="OK" Description=" SerialNO:123” />

</root>

Если Result=Error, то тег Description содержит описание ошибки.

Если Result= OK, то тег Description содержит серийный номер ФР (SerialNO).

Запрос статуса смены ФР (команда FR_GETSESSIONSTATUS)

Без параметров.

Формат ответа:

<?xml version="1.0" encoding="windows-1251"?>

<root>

   <Response Result="OK" Description="Смена открыта” />

</root>

Если Result=Error, то тег Description содержит описание ошибки.

Если Result= OK, то тег Description содержит описание статуса смены (открыта/закрыта/просрочена)

Проверка достоверности марки (команда FR_CHECKKM)

Параметры:
KM – считанный код марки (без преобразований)
CHECK_TYPE – тип чека, в котором предполагается участие маркированного товара (SALE или RETURN).

Проверку маркированного товара лучше проводить до формирования чека, т.к. если при печати строки произойдёт ошибка, то весь чек будет аннулирован.

Перед проверкой, при необходимости, следует открыть смену на ФР.

Печать чека продажи/возврата (команда FR_PRINTCHECK)

Параметры:

CODEPAGE - Кодировка текста: UTF8, если текст не в кодировке ANSI. Может быть опущен (по умолчанию используется ANSI).

USER_CODE - Код оператора (целое, 1 – 30). Может быть опущен.

USER_NAME - Имя оператора. Может быть опущен.

ReportElectronically - Признак «Без печати на чековую ленту». Возможные значения: 

Регистр не имеет значения (как для имени параметра, так и для его значения).

DATA – буфер чека

При получении команды «Печать чека» FRServer проверяет:

- текущее состояние документа (чека). Если есть незакрытый чек, то FRServer отменяет его.

- текущее состояние смены. Если смена закрыта, то FRServer открывает новую смену.

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

Формат буфера чека

Передаваемый буфер имеет следующий вид:

 <?xml version="1.0" encoding="utf8"?>
<check type="Тип операции"

customer=””

customerName=”ООО Софт-Вест”

customerINN=”123456789”

dept=\"1\"  

cash_sum="Сумма внесённой наличной оплаты"

card_sum="Сумма оплаты по карте"

credit_sum="Сумма безналичной оплаты по типу 3"

sum4="Сумма безналичной оплаты по типу 4"

avance_sum=\"Сумма предварительной оплаты (авансом)\"

discount_sum=\"Скидка на чек по округлению (меньше рубля)\" >

<line

         code="Код товара"

         name="Наименование товара"

          price="Цена товара"

          quantity="Кол-во"  

          tax="Номер налоговой группы"

          payment_type=\"Признак способа расчета\"

          payment_item=\" Признак предмета расчета \" >

         <discount sum="Сумма скидки"/>

   </line>
   …

   <line

           dept=\"1\"

           code="Код товара"

           name="Наименование товара"

           price="Цена товара"

           quantity="Кол-во" 

           tax=="Номер налоговой группы" >

          <charge sum="Сумма наценки"/>

   </line>
   …
   …

  <footer>

      ……

  </footer>

</check>

Атрибуты ноды «check»:

Атрибут

Тип

Обязательность

Описание

type

строка

+

Тип операции

customer

строка

 

Телефон или электронный адрес покупателя

customerName

строка

 

Наименование организации-покупателя

customerINN

строка

 

ИНН организации-покупателя

dept

целое

 

Номер отдела

cash_sum

число

+

Сумма внесённой наличной оплаты

card _sum

число

Сумма оплаты по карте

credit _sum

число

Сумма безналичной оплаты по типу 3

sum4

число

Сумма безналичной оплаты по типу 4

avance_sum

число

 

Сумма предварительной оплаты (авансом)

discount_sum

число

 

Скидка на чек по округлению

Если указана Сумма предварительной оплаты (аванс), то сумма чека по факту уменьшается на сумму аванса.

Сумма чека также учитывает скидку на округление.

Т.е. при продаже товаров на сумму 100.20 (аванс 20.00, округление 0.20) общая сумма по чеку для оплаты будет 80.00.

Допускается наличие только одного, двух, трёх или всех четырёх параметров с суммой оплаты. Требования:  общая сумма безналичной оплаты (card _sum + credit _sum + sum4) не должна превышать сумму чека и общая сумма оплат не может быть меньше суммы чека.

Атрибуты ноды «line»:

Атрибут

Тип

Обязательность

Описание

dept

целое

 

номер отдела

code

строка

 

код товара

name

строка

+

наименование товара

price

число

+

цена товара

quantity

число

+

количество товара

tax

целое

 

номер ставки НДС

payment_type

целое

 

Признак способа расчёта

payment_item

целое

 

Признак предмета расчёта

barcode

строка

 

Штрих-код (маркированный товар)*

Таблица 24

Наименование ставки НДС

Формат ЭФ

Формат ПФ

ставка НДС 18%

1

«НДС 18%»

ставка НДС 10%

2

«НДС 10%»

ставка НДС расч. 18/118.

3

«НДС 18/118»

ставка НДС расч. 10/110

4

«НДС 10/110»

ставка НДС 0%

5

«НДС 0%»

НДС не облагается

6

По новым нормам значение налоговой группы указывать обязательно. Если переданная ставка не соответствует указанным в таблице или не указана, то она принимается равной 1 (НДС 18%).

В соответствии с приказом ФНС России от 21марта 2017 г. № ММВ-7-20/229@: Значения реквизита «признак способа расчёта» и перечень оснований для присвоения соответствующих значений реквизиту, а также формат данных этого реквизита ФД в печатной форме:

Значение реквизита

Перечень оснований для присвоения реквизиту «признак способа расчёта» (тег 1214) соответствующего значения реквизита

Формат ПФ

1

Полная предварительная оплата до момента передачи предмета расчёта

«ПРЕДОПЛАТА 100%» или «1» или может не печататься

2

Частичная предварительная оплата до момента передачи предмета расчёта

«ПРЕДОПЛАТА» или «2» или может не печататься

3

Аванс

«АВАНС» или «3» или может не печататься

4

Полная оплата, в том числе с учётом аванса (предварительной оплаты) в момент передачи предмета расчёта

«ПОЛНЫЙ РАСЧЕТ» или «4» или может не печататься

5

Частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит

«ЧАСТИЧНЫЙ РАСЧЕТ И КРЕДИТ» или «5» или может не печататься

6

Передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит

«ПЕРЕДАЧА В КРЕДИТ» или «7» или может не печататься

7

Оплата предмета расчёта после его передачи с оплатой в кредит (оплата кредита)

«ОПЛАТА КРЕДИТА» или «9» или может не печататься

Если переданный признак способа расчёта не соответствует  таблице или не указан, он принимается равным 1.

Значения реквизита «признак предмета расчёта» и перечень оснований для присвоения соответствующих значений реквизиту, а также формат данных этого реквизита ФД в печатной форме:

Значение реквизита

Реквизит «наименование предмета расчёта» (тег 1030) содержит сведения

Формат ПФ

1

о реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар)

«ТОВАР» или «Т» или может не печататься

2

о реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар)

«ПОДАКЦИЗНЫЙ ТОВАР» или «АТ» или может не печататься

3

о выполняемой работе (наименование и иные сведения, описывающие работу)

«РАБОТА» или «Р» или может не печататься

4

об оказываемой услуге (наименование и иные сведения, описывающие услугу)

«УСЛУГА» или «У» или может не печататься

5

о приёме ставок при осуществлении деятельности по проведению азартных игр

«СТАВКА АЗАРТНОЙ ИГРЫ» или «СТАВКА ИГРЫ» или «СА» или может не печататься

6

о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр

«ВЫИГРЫШ АЗАРТНОЙ ИГРЫ» или «ВЫИГРЫШ АИ» или «ВА» или может не печататься

7

о приёме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приёме лотерейных ставок при осуществлении деятельности по проведению лотерей

«ЛОТЕРЕЙНЫЙ БИЛЕТ» или «СТАВКА ЛОТЕРЕИ» или «СЛ» или может не печататься

8

о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей

«ВЫИГРЫШ ЛОТЕРЕИ» или «ВЫИГРЫШ ЛОТЕРЕИ» или «ВЛ» или может не печататься

9

о предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации

«ПРЕДОСТАВЛЕНИЕ РИД» или «РИД» может не печататься

10

об авансе, задатке, предоплате, кредите, взносе в счёт оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчёта

«ПЛАТЕЖ» или «П», «ВЫПЛАТА» или «В» или может не печататься

11

о вознаграждении пользователя, являющегося платёжным агентом (субагентом), банковским платёжным агентом (субагентом), комиссионером, поверенным или иным агентом

«АГЕНТСКОЕ ВОЗНАГРАЖДЕНИЕ» или «АВ»

12

о предмете расчёта, состоящем из предметов, каждому из которых может быть присвоено значение от «0» до «11»

«СОСТАВНОЙ ПРЕДМЕТ РАСЧЕТА» или «СПР» или может не печататься

13

о предмете расчёта, не относящемуся к предметам расчёта, которым может быть присвоено значение от «0» до «12»

«ИНОЙ ПРЕДМЕТ РАСЧЕТА» или «ИПР» или может не печататься

Если переданный признак предмета расчёта не соответствует таблице или не указан, он принимается равным 4.

ФР «Атол» не поддерживает признак предмета расчёта 13.

Маркировка

Если штрих-код содержит символы идентификаторов применения 0x1d, этот символ должен замениться на отображаемый символ 0xa4 (¤).

Например, считанный штрих-код

010290000030004021йЮФ?ГнЗЮ9рфуЙ\u001d918029\u001d9257Е+шЯецазмлч7йреЧмчь0фонЛП4уяо14сТзс.п2Т+ь34фЫ5НвЫ1ДфщдОМщффВДТВТме9ФуЦмУМ+73тИ2й3И1ц==

передаётся в виде

010290000030004021йЮФ?ГнЗЮ9рфуЙ¤918029¤9257Е+шЯецазмлч7йреЧмчь0фонЛП4уяо14сТзс.п2Т+ь34фЫ5НвЫ1ДфщдОМщффВДТВТме9ФуЦмУМ+73тИ2й3И1ц==

Скидка/наценка (ноды «discount», «charge») – это информационные строки чека, поскольку фактическая цена в товарной строке должна уже включать скидку/наценку. Эти ноды вложены в ноду line. Могут отсутствовать.

Нода “footer” – текстовая, не содержит атрибутов.

Нода «check» в посылке - единственная; нод «line», «discount», «charge» может быть несколько.

Все суммы и цены имеют один формат.

Печать текстового буфера  (команда FR_PRINTTEXT)

Параметры:

CUT=1 означает отрезку после окончания печати.

DATA – текстовый буфер с разделителями строк CRLF (\r\n).

  1. В строке буфера может содержаться указатель на печать QR-кода в виде:
    <qr>1234567890
    Указанное в строке значение печатается в виде QR-кода
  2. В строке буфера может содержаться указатель на жирную (bold) печать в виде:
    <b>1234567890
    Указанное в строке значение печатается жирным шрифтом

    Используется только для ФР «Штрих»

  3. В строке буфера может содержаться указатель на фонт в виде:
    <font: [Номер фонта ККМ][d - признак двойной ширины и высоты]>

Установленный фонт действует на весь последующий текст вплоть до нового тега font.

Пример:

Строка1
<
font: 2d>
Строка2
Строка3
<
font: 3>
Строка4

“Строка1” печатается фонтом по умолчанию.

“Строка2” и “Строка3” печатаются фонтом №2 с двойной шириной и высотой.

“Строка4” печатается фонтом №3 с обычной высотой-шириной.

Используется только для ФР «Атол» (номера фонтов 0 – 7) и «Штрих» (номера фонтов 0 – 255 зависят от пришивки, в реальности используются только некоторые из первого десятка).

Невозможно одновременное использование с атрибутом bold (<b>)

Регистр тегов не имеет значения.

Буфер может содержать последовательность "\x1bi", означающую отрезку чека. После отрезки происходит печать оставшейся части буфера.

 

Команды

Команды для ПТ

Для всех команд платёжной системы можно указывать признак вывода слипа на ФР (параметр ReportElectronically).

Ответ при успешном выполнении команды содержит параметры (в ноде Response):

Нода <Data> содержит текст слипа.