Введение

Интерфейс предназначен для транслирования информации по протоколу HTTP о событиях с кассовой станции на адрес, указанный в параметре драйвера.
Основная задача - передача данных об изменениях в заказах и других событиях кассовой станции.

Есть два варианта настройки механизма отправки уведомлений:

  • Механизм подписок для версии 7.6.5.440 и старше
  • Через интерфейс HTTP Order Notify для версий ниже 7.06.05.440

Схема работы

После старта драйвер находится в ожидании событий от кассы, либо завершения работы кассового сервера.

События передаваемые драйвером идут в порядке поступления. На текущий момент размер очереди равен 256. При достижении максимального количества прием новых событий приостанавливается до освобождения места для события. Это необходимо для предотвращения переполнения памяти и аварийной остановки кассового сервера, если отправка сообщений невозможна.

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

Данные пытаются отправляться сразу при поступлении в драйвер. Времени ожидания события "приход данных" нет.

Драйвер загружается при старте кассового сервера. Независимо от наличия кассовой станции в очередь ставится сообщение о запуске кассового сервера с Situation="1". Событие аналогично старту кассы, но с ограниченным количество узлов.

Пример сообщения после загрузки и инициализации кассового сервера:

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2020-01-14T15:38:23" Situation="1" seqnumber="1" guid="{9ECCB1B5-97EE-4B88-9840-8568F05586D0}" name="Started" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Server id="15002"/>
<Item/>
</a>
XML

В данном событии указан только идентификатор кассового сервера. Если адрес задан в свойствах кассового сервера, то он уведомляет драйвер о готовности к работе. Далее происходит это событие. 

После старта кассовой станции в очередь ставится похожее сообщение, но с расширенным набором узлов:

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:17:58" Situation="1" seqnumber="1" guid="{9ECCB1B5-97EE-4B88-9840-8568F05586D0}" name="Started" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Item/>
</a>
XML

В нем указана расширенная информация о кассовом сервере и данные о кассовой станции. Данный механизм позволяет разделить события загрузки кассового сервера и кассовой станции для их раздельной обработки.

Указанный в примере GUID не является константой.

Поддерживаемые команды, передающиеся драйвером в атрибуе Situation:

SituationСобытие
1Старт кассового сервера или кассовой станции
3Изменение заказа
4

Расчет заказа

5

Закрытие чека

9

Закрытие заказа

10

Блокировка кассовой станции (logoff)

11

Создание нового заказа

12

Открытие существующего заказа

13

Сохранение заказа

14

Удаление чека

18

Закрытие кассовой станции

21

Логин на кассовую станцию

24Переход в состояние печати чека

Лицензирование интерфейса HTTP Order Notify

Если требуется более одного подключения, необходимо лицензировать интерфейс HttpOrderNotify.
Активировать лицензию следует начиная с версии 7.6.5.459. Лицензия в системе лицензирования называется R-Keeper модуль Интерфейс уведомлений о заказах 12 мес ПО.
Подробный процесс получения лицензии описан в статье Генерация лицензий без кода запроса

Интерфейс HTTP Order Notify

HTTP Order Notify работает на стороне кассового сервера к которому подключена кассовая станция. Драйвер добавляется на кассовый сервер.
Для корректной загрузки драйвера необходимо привязать к нему интерфейс для кассового сервера. Об этом ниже.

Для версий r_keeper младше 7.6.5

Добавьте драйвер HTTP Order Notify на кассовый сервер:


Параметры:

НазваниеОписание и возможные значения
Log FileПуть к файлу, который будет использоваться в качестве лога действий драйвера. Может отсутствовать, но в этом случае будет затруднено выявление проблем при работе

LogLevel

Уровень логирования, может принимать одно из трех значений:

  • 0 - errors only — В этом режиме в лог попадают только самые важные сообщения (например информация о загрузке интерфейса), либо сообщения о произошедших ошибках: превышение количества событий в очереди, сбой отправки данных на HTTP сервер и т.п.
  • 1 - input xmls and errors — В этом режиме в дополнение к режиму errors only добавляются некоторые важные сообщения, например старт отправки XML на адрес HTTP-сервера.
  • 2 - max log — Наиболее полный режим логирования, содержит максимально подробную информацию о работе драйвера, включая входящие и исходящие XML, текущее состояние очереди отправки и др.
DestURLsHTTP-адрес, на который будет производится отправка данных. Задается в общепринятом формате адресов URL.
Может содержать только один адрес. При необходимости отправки данных на несколько HTTP-серверов для каждого из них должен быть добавлен свой драйвер HTTP Order Notify

Для загрузки драйвера кассовым сервером привяжите его к интерфейсу:

  1. В менеджерской станции перейдите на вкладку сервис
  2. Нажмите на вкладку Интерфейсы
  3. В справочнике добавьте новый интерфейс и заполните параметры:
НазваниеОписание и значение
[Название кассового сервера]выберите драйвер, добавленный на кассовый сервер
Общее имя DLLукажите имя файла драйвера, всегда httpnotf.dll

     4. Перезагрузите кассовый сервер

Для версии r_keeper 7.6.5 

Параметры работы драйвера настраиваются в свойствах кассового сервера в разделе HTTP Order Notify

Параметры:

НазваниеОписание и возможные значения
Имя файла логаПуть к файлу, который будет использоваться в качестве лога действий драйвера. Может отсутствовать, но в этом случае будет затруднено выявление проблем при работе. К имени файла лога добавляется порядковый номер адреса в списке адресов, начиная с нуля. Т.е. если имя файла лога httpnotf.stk, то для первого адреса подписки имя файла будет httpnotf0.stk, для второго - httpnotf1.stk и т.д.

Уровень лога

Уровень логирования, может принимать одно из трех значений:
  • 0 - Только ошибки — В этом режиме в лог попадают только самые важные сообщения (например информация о загрузке интерфейса), либо сообщения о произошедших ошибках: превышение количества событий в очереди, сбой отправки данных на HTTP сервер и т.п.
  • 1 - XML и ошибки — В этом режиме в дополнение к режиму "Только ошибки" добавляются некоторые важные сообщения, например старт отправки XML на адрес HTTP-сервера
  • 2 - Полная информация — Наиболее полный режим логирования, содержит максимально подробную информацию о работе драйвера, включая входящие и исходящие XML, текущее состояние очереди отправки и др.
DestURLsHTTP-адреса, на которые будет производится отправка данных. Задаются в общепринятом формате адресов URL. Может содержать несколько адресов, разделенных точкой с запятой. На указание нескольких адресов действуют ограничения по лицензированию вровар

Значение параметра DestURLs используется только при старте кассового сервера. Изменив этот параметр, перезапустите кассовый сервер для изменения списка адресов. Чтобы список адресов изменился во время работы сервера, используйте механизм подписок.

Для r_keeper 7.6.5 и старше

Начиная с версии 7.6.5.371 настройки Http Order Notify переместились из Устройств в свойства кассового сервера. Порядок действий для этих версий такой:

  1. В параметре драйвера DestURLs пропишите строку подключения в виде:
    https://имя_пользователя:пароль_пользователя@адрес_сервера_KDS_PRO:порт_сервера_KDS_PRO/orderTaker
  2. Сохраните изменения

  3. Перезапустите кассовый сервер

    Если требуется указать несколько строчек подключения, их можно указать через точку запятой ";".
    Например: http://127.0.0.1:2121/api/httpNotify/postOrders;https://127.0.0.1:1234/orderTaker

    Если используется несколько строчек подключения, необходимо пролицензировать свойство кассового сервера HTTP Order Notify. Подробнее читайте в статье Лицензирование.

Для r_keeper младше 7.6.5

Если же у вас версия r_keeper меньше 7.6.5, то интерфейс HTTP Order Notify необходимо на кассовый сервер добавить самостоятельно. Инструкция ниже

  1. Для работы KDS PRO требуется драйвер не ниже 18 версии. Поэтому, если ваша версия ниже — перед добавлением интерфейса на кассовый сервер, скачайте драйвер с FTP: ftp://ftp.ucs.ru/rk7/other/KDS_PRO/Extra_Files/httpnotf.udb
  2. Скопируйте файл httpnotf.udb с заменой в папку сервера справочников
  3. Перезапустите кассовый сервер

  4. Добавьте на кассовый сервер драйвер HTTP Order Notify:

  5. Настройте драйвер для всех кассовых серверов по необходимости.

  6. В параметре драйвера DestURLs пропишите строку подключения в виде:
    https://имя_пользователя:пароль_пользователя@адрес_сервера_KDS_PRO:порт_сервера_KDS_PRO/orderTaker

  7. Имя пользователя и пароль указывать не обязательно. Вписывайте их только, если они есть в личном кабинете. Эти данные есть в личном кабинете, их описание ниже. Порт сервера находится в файле настроек kds_pro.config.
  8. Перейдите в Сервис > Интерфейсы и создайте новый интерфейс
  9. В разделе Файлы библиотек (DLL) выберите нужный ресторан и укажите драйвер кассовому серверу HTTP Order Notify
  10. Активируйте интерфейс и сохраните.

В версиях старше r_keeper 7.6.5 драйвер HTTP Order Notify работает только через механизм подписок, использование интерфейса не поддерживается.

Механизм подписок

Для отправки кассовым сервером уведомлений об изменениях отправьте POST-запрос к кассовому серверу:

https://127.0.0.1:8001/rk7api/v1/subscribe.xml?service=httpnotf&url=https://HTTP_KDS2:1@172.18.2.2:1234/orderTaker
XML

где:

ПараметрНазначение
serviceНаименование сервиса, должно быть httpnotf
urlURL, на который необходимо выполнять отправку уведомлений

Указанный в параметре URL адрес будет добавлен к списку существующих адресов рассылки. На него будет сразу отправлено событие с name=Started.

Если количество адресов превысит доступное, то r_keeper выдаст ошибку "HttpOrderNotify: address URL is disabled, license check failed"

Отказ от подписки

Для отказа от подписки отправьте DELETE-запрос

https://127.0.0.1:8001/rk7api/v1/subscribe.xml?service=httpnotf&url=https://HTTP_KDS2:1@172.18.2.2:1234/orderTaker
XML

Переданный в параметре url адрес будет исключен из списка рассылок. Если в очереди оставались сообщения, то отправлены они не будут.

Примеры XML

Авторизация на кассовой станции

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:18:00" Situation="21" seqnumber="3" guid="{81A89081-D394-4070-BD37-A8E54CCA7B56}" name="Login" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Waiter id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Waiter>
<Item/>
</a>
XML

Создание нового заказа

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:18:33" Situation="11" seqnumber="13" guid="{833F0492-E8ED-4F34-81BC-8A9F4D73A995}" name="New Order" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Waiter id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Waiter>
<Order visit="477823977" orderIdent="256" guid="{763C7F09-875A-438A-B6CB-25F7D3F74741}" url="http://code.ucs.ru/qr?id=209A9A2B872A4728BEC8F0B09C667E6A763C7F09875A438AB6CB25F7D3F74741B6995A91" orderName="8888888888" locked="1" version="0" crc32="0" orderSum="0" unpaidSum="0" discountSum="0" totalPieces="0" seqNumber="1" paid="1" finished="0" persistentComment="" nonPersistentComment="" openTime="2019-12-18T17:18:32">
<Creator id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Creator>
<Waiter id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Waiter>
<OrderCategory id="10033" code="1" name="Основная"/>
<OrderType id="10069" code="9001" name="не выбрано"/>
<Table id="1000259" code="93" name="8888888888"/>
<Station id="15003" code="1" name="MM_CASH"/>
<Guests count="1">
<Guest guestLabel="1"/>
</Guests>
</Order>
<Session uni="2" line_guid="{39271E37-867D-41FF-99B8-59CB182323E9}" state="1" sessionID="2" isDraft="0" remindTime="2019-12-18T17:18:00" startService="2019-12-18T17:18:33" printed="0" cookMins="0">
<Station id="15003" code="1" name="MM_CASH"/>
<Author id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Author>
<Creator id="1" code="7" name="Администратор">
<Role id="100007" code="7" name="Администраторы"/>
</Creator>
<Course id="1" code="1" name="Готовить позже"/>
<PriceScale id="3" code="1" name="Основная"/>
<TradeGroup id="7" code="1" name="По умолчанию"/>
</Session>
<Item ClassName="TOrder"/>
</a>
XML

Решение проблем

При работе драйвер добавляет информацию о своей работе в логи для упрощения локализации возникших проблем при работе.
Регулярно возникающая проблема - данные не приходят на принимающий HTTP-сервер. Здесь следует проверить корректность указания адреса в параметре DestURLs драйвера и работоспособность HTTP-сервера. Если невозможно отправить данные, в логе будут сообщения с подстрокой "HTTP: Post error", например:

18.12.2019 16:25:32:343 HTTP: Post error: Socket Error # 10061
XML

Часто встречающиеся коды ошибок:

Код HTTP

Описание
10061Connection refused - невозможно соединиться с сервером
10054Connection reset by peer - соединение сброшено сервером

В этом случае необходимо проверить настройки HTTP-сервера

В сообщениях вида:

SEND_THREAD: Signal [Send] ENTER, items in queue: 19
XML

содержится информация о текущем количестве объектов в очереди. При достижении максимального значения в логе будет сообщение:

XML: Can't add command. Max queue size: 256
XML