Страница 1 из 1

Общий формат XML-протокола

Добавлено: 20 дек 2015, 21:39
RndIT
Для управления кассовым сервером QKkmServer был выбран формат XML-сообщений, т.к. этот формат может обеспечить следующие важные свойства протокола:
  • независимость от программной и аппаратной среды как клиента, так и сервера
  • для кодирования международных символов используется UTF-8
  • в отличии от бинарных протоколов, текстовый протокол не критичен к задержкам в процессе передачи. Лишь бы сообщение оказалось передано до конца и без искажений (за этим в минимальной степени следит сам протокол TCP)
  • для максимальной гарантии защиты сообщения от искажения может (опционально) использоваться механизм сертификатов SSL.

В протоколе различается два типа сообщений: запрос и ответ.
После получения запроса (корректного или не корректного) сервер обязан вернуть ответ (результат исполнения команды или ошибку). После этого сервер отключает клиента. Таким образом, за одно подключение кассовый сервер может выполнить только одну команду XML-протокола.

Структура сообщения ЗАПРОС

Код: Выделить всё

<ControlProtocol messageType="request">
КОМАНДА[+параметры]
</ControlProtocol>



Структура сообщения ОТВЕТ

Код: Выделить всё

<ControlProtocol messageType="answer">
<error id="КОД_СТАТУСА" text="ОПИСАНИЕ_СТАТУСА"/>
<НАЗВАНИЕ_КОМАНДЫ [ОТВЕТ_ФР] />
</ControlProtocol>

В нормальной ситуации КОД_СТАТУСА равен нулю, что соответствует значению ОПИСАНИЕ_СТАТУСА "Ошибок нет".
Для отслеживания логических цепочек команд в состав ответа включается НАЗВАНИЕ_КОМАНДЫ исполнение которой производилось. Если команды возвращает ответ, то он будет оформлен в виде пар АТРИБУТ=ЗНАЧЕНИЕ в поле ОТВЕТ_ФР.

Пример пары ЗАПРОС-ОТВЕТ
В качестве примера возьмем команду "Запрос денежного регистра"

Сообщение ЗАПРОС
Будет запрошен 195-й денежный регистр (сумма возвратов по первой форме оплаты "Наличными").

Код: Выделить всё

<ControlProtocol messageType="request">
   <getMoneyReg idReg="195" />
</ControlProtocol>


Сообщение ОТВЕТ

Код: Выделить всё

<ControlProtocol messageType="answer">
    <error id="0" text="Ошибок нет"/>
    <getMoneyReg idReg="195" Value="32010"/>
</ControlProtocol>

Кассовый сервер сообщает, что команда getMoneyReg для денежного регистра выполнена без ошибок. Сумма накоплений Value составляет 32010 МДЕ.

Все денежные величины указываются в МДЕ - Минимальных Денежных Единицах, т.е. копейках.
Все весовые/количественные величины указываются в МКЕ - Минимальных Количественных Единицах, граммах.


Таким образом, 32010 МДЕ = 32010 копеек = 320 рублей 10 копеек

Re: Общий формат XML-протокола

Добавлено: 26 янв 2016, 08:57
Logger
Some questions
1. Являются ли все параметры, перечисленные в командах обязательными? По некоторым (в ПРОДАЖЕ, например) есть расшифровка на форуме, но не по всем. Tax в Продаже; Discount, Text а Закрытии чека. Если Text обязателен, но мне не нужен, будет ли выполнен перевод строки при задании параметра Text = ""?
Если есть неиспользуемые, но обязательные, может быть стоит в следующих версиях ввести понятие "параметр по умолчанию"? К примеру, мне совершенно не нужен параметр "Дисконт" в итоге чека, и, если я его не упоминаю, он ставится равным нулю, то же самое с налогом, текстом.
2. Хотелось бы видеть примеры структуры. С кассами никогда не работал, насколько я понял, чек состоит из нескольких команд:
ПРОДАЖА_1
ПРОДАЖА_2
ПРОДАЖА_N
ЗАКРЫТИЕ ЧЕКА
ОБРЕЗКА ЧЕКА(?)
В случае отмены чека может использоваться:
ПРОДАЖА_1
ПРОДАЖА_2
АННУЛИРОВАНИЕ ЧЕКА
- Каким образом выглядит структура возврата? Можно возвращать только когда чек еще не закрыт или когда закрыт тоже?
- Нужно ли в каждом чеке вводить ОБРЕЗКУ ЧЕКА или она будет проводиться автоматом (через Supervisor, например, при печати Х-отчета регистратор сам обрезает);
3. Некоторые команды, возможно, стоит пояснить: ЗАПРОС ДАННЫХ ДЕНЕЖНОГО РЕГИСТРА, ЗАПРОС ДАННЫХ ИЗ ОПЕРАТИВНОГО РЕГИСТРА. Позвонил знакомым ЦТО-шникам, даже они не знаю что это такое. Возможно оно и не нужно.
ПРОДВИНУТЬ ДОКУМЕНТ - для чего может использоваться?

Пока вроде все.

Re: Общий формат XML-протокола

Добавлено: 26 янв 2016, 10:04
RndIT
Logger писал(а):1. Являются ли все параметры, перечисленные в командах обязательными?

В настоящее время идёт наполнение форума актуальной информацией о командах протоколов. Я обязательно сделаю акцент на обязательных параметрах и не обязательных, с указанием значений по-умолчанию.

Logger писал(а):2. Хотелось бы видеть примеры структуры. С кассами никогда не работал, насколько я понял, чек состоит из нескольких команд:

Да, типовая продажа состоит из операций
  • добавления товаров (с указанием, по необходимости: номера налоговой группы, дисконта на товар и т.п).
  • операции оплаты (закрытия) чека (указывается одна из 4-х форм оплаты суммой не менее чем общая сумма по чеку, далее по необходимости: общий налог на чек, общая скидка на чек и т.п. в соответствии с форматом команды)
По поводу отрезки: по-умолчанию фискальные регистраторы настроены на автоматическую отрезку чека после успешного исполнения команды закрытия (оплаты) чека. Но иногда ФР настраиваются иначе (распишу чуть ниже).

Logger писал(а):В случае отмены чека может использоваться:
ПРОДАЖА_1
ПРОДАЖА_2
АННУЛИРОВАНИЕ ЧЕКА
- Каким образом выглядит структура возврата? Можно возвращать только когда чек еще не закрыт или когда закрыт тоже?

По поводу возврата. Возврат - это обратная операция продаже. Отличаются только последней командой. Для того, чтобы операция возврата могла быть осуществлена, в текущей смене по форме оплаты по которой будет делаться возврат, должны быть накопления.
Например, надо сделать возврат наличными 100 рублей.
Соответственно, в кассе к этому моменту должно быть минимум 100 рублей наличными. Если их нет, то вернётся ошибка.
Да, типовая операция возврата продажи состоит из операций
  • добавления товаров (с указанием, по необходимости: номера налоговой группы, дисконта на товар и т.п).
  • операции возврата товара (указывается одна из 4-х форм оплаты суммой не менее чем общая сумма по чеку, далее по необходимости: общий налог на чек, общая скидка на чек и т.п. в соответствии с форматом команды)

Аннулирование - это иное. Это когда чек ещё не закрыт, а принято решение его отменить. Например, клиент отказался от покупки, т.к. не хватило средств.

- Нужно ли в каждом чеке вводить ОБРЕЗКУ ЧЕКА или она будет проводиться автоматом (через Supervisor, например, при печати Х-отчета регистратор сам обрезает);

Это настраивается через заводскую утилиту Штрих-М "Тест драйвера"


3. Некоторые команды, возможно, стоит пояснить: ЗАПРОС ДАННЫХ ДЕНЕЖНОГО РЕГИСТРА, ЗАПРОС ДАННЫХ ИЗ ОПЕРАТИВНОГО РЕГИСТРА. Позвонил знакомым ЦТО-шникам, даже они не знаю что это такое. Возможно оно и не нужно.


Горе этим ЦТОшникам :) Поясню.
Все денежные операции проводятся по внутренним регистрам ФР. Есть регистр накопления продаж, т.е. суммы продаж, возвратов и т.п. Это денежные (суммовые) регистры.

Есть оперативные регистры, например, количество (в штруках) пробитых чеков, номер смены и т.п.
Я в соответствующем разделе распишу регистры по номеру и назначению.


ПРОДВИНУТЬ ДОКУМЕНТ - для чего может использоваться?

Для принудительной промотки ленты (обычно, чековой). Допустим, имеем не настольный ФР, а встраиваемый в терминал оплаты. Расстояние от ФР до края щели - сантиметр. Что будет удобнее клиенту, если чек короткий (2-3 см): пытаться захватить краешек чека, который только-только появился в прорези, или распечатать чек + продвинуть чек клиенту в руки и обрезать его? Думаю -- второе. Тут как раз и объясняется ситуация, когда автообрезка чека не подходит.

Re: Общий формат XML-протокола

Добавлено: 30 май 2016, 13:42
Logger
А можно получить все коды ошибок? На текущий момент интересует
<error id="199" text="Поле не редактируется в данном режиме"/>

Выдает в ответ на
<ControlProtocol messageType="request">
<Beep />
</ControlProtocol>