Купоны

С помощью FarCards реализована возможность передавать на кассу список купонов, доступных гостю или по идентификатору. На кассе — возможность выбрать купон из списка, получить содержимое купона для добавления в заказ и передать информацию о факте использования купона во внешнюю систему.

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

  • Да
  • Нет
  • Предлагать.

Если в чеке есть купон или содержимое купона, то система может либо добавить элементы купона в чек со скидкой, либо добавить в элементы чека скидку.

Элементы купона, которые есть в блюде, должны быть помечены специальным значком.

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

  1. Купон или набор купонов назначаются на карту гостя, например, как постоянному клиенту

  2. Купон или набор купонов не зависит от гостя, например, за покупку определенного блюда

  3. Купон один.

Купон один

Номер купона вводится как номер карты или считывается, например, через штрихкод. Затем передается в функцию GetCardInfoEx как номер карты.

В ответ внешняя система должна вернуть OutKind = 3(couponcontent(xml) — для передачи списка блюд в ответ на авторизацию, обработчик должен также поддерживать OutKind=1 (xml).

<?xml version="1.0" encoding="utf-8"?>
<ident_info>
  <overide_info code="123456"/>
  <parent_ident code="4547059" printname="Василий Петрович"/>
 
  <item_content hint="Ваш купон позволяет выбрать 2 товара из первой группы и любой товар из второй.">
    <group name="group name" printname="Имя группы" order="1" maxquant="2">
      <item code="123" kind="summ" val="10.00" order="3" max="3" default="1" disccode="13" comment="Комментарий"/>     
      <item code="321" kind="percent" val="10.00"order="2" max="2" disccode="123"/>            
      <item code="213" kind="price" val="10" order="10" max="1"  />                 
    </group>
    <group name="group name2" printname="Имя группы2" order="2">
      <item code="423" kind="summ" val="130" order="1" line_id="433242" comment="Комментарий"/> 
      <item code="621" kind="percent" val="1230" order="3" />            
      <item code="713" kind="price" val="110" order="2" autorecalc="1"/>          
    </group>     
    <group name="group name3" printname="Скидки на заказ" order="2">
      <item printname="Скидка на заказ" disccode="1122" kind="summ" val="111"/>          
    </group>     
 
  </item_content>
</ident_info>
XML
  • Тег overide_info используется для изменения номера карты.
  • Тег parent_ident служит для указания кода и подписи к кнопке, нажатие на которую вызовет авторизацию по переданному коду. Ожидается что такая авторизация вернет XML по типу 4.
  • Атрибут disccode=«123» указывает на код скидки, которая должна быть использована для хранения информации о применении купона. Значение по умолчанию в RK7 — в параметре системы PDSDefCouponDisc «Скидка купонов». Скидка должна быть сконфигурирована так, чтобы ее можно было применить. Сумма скидки рассчитывается с учетом правила скидки и суммы купона — берётся минимальное по модулю значение.
  • Атрибут max указывает на максимально возможное количество элементов по данному правилу. Если значение не указано, то по умолчанию значение равно единице.
  • Атрибут default указывает на количество элементов по умолчанию по данному правилу. Если значение не указано, то по умолчанию значение равно нулю.
  • Если атрибут maxquant не указан, то по умолчанию имеет значение 0 и трактуется как «без ограничений».
  • Атрибут kind указывает на тип элемента купона. Может быть:

    • summ — купон предоставляет скидку в виду суммы на указанное блюдо.

    • percent — купон предоставляет скидку в виде процента на указанное блюдо.

    • price —  купон дает право устанавливать определенную цену на указанное блюдо. 

  • Для атрибута line_id можно указать значение — GUID строки, к которой будет добавлен элемент купона. Если значение не задано — элементы добавляются иначе, через модификацию исходной строки. Обратите внимание, что RK7 поддерживает и UNI строки.
  • В info.discount должна быть передана скидка, ассоциируемая с этим купоном.
  • Атрибут autorecalc — необязательный. Начиная с версии 27, при значении, равном одному, означает, что после обработки этого купона, этого item, необходимо заново вызвать GetCardInfoEx, передав заказ, содержащий информацию о только что примененном купоне для получения новой информации о карте, включая новый лимит скидки и новые остатки по валютам.
  • Атрибут — comment необязательный. Если заполнен, то переданный текст будет отображаться на кнопке купона в поле Комментарий.
  • Если code не задан или равен 0, а задан printname, то скидка применяется на заказ.

Остальные элементы структуры info игнорируются.

Выбор идентификатора

Выбор идентификатора может быть использован для разных задач по типу:

  • Для выбора купона из набора
  • Для выбора счета гостя по комнате.

Номер купона вводится как номер карты или считывается, например, через штрихкод. Затем передается в функцию GetCardInfoEx как номер карты.

В ответ внешняя система должна вернуть OutKind = 4-ident_list(xml). Эта команда служит для передачи списка идентов, например счетов, жильцов, мастер-купонов, в ответ на авторизацию. Обработчик должен также поддерживать OutKind=1 (xml).

<?xml version="1.0" encoding="utf-8"?>
<ident_list hint="Выберите любой купон!">
  <group printname="Имя группы" order="1"  image="base64(bmp)" image_scale="false">
    <ident code="70589" printname="Карта№2" order="3" image="base64(bmp)" image_scale="true" comment="Комментарий"/>     
    <ident code="70586" printname="Гость№1" order="25" default="1" />            
    <ident code="70519" printname="Купон№5" order="10" />                 
  </group>
  <group printname="Имя группы2" order="2">
    <ident code="70489" printname="Купон №5" order="1" />     
    <ident code="70453" printname="Купон №7" order="3" />            
    <ident code="70413" printname="Купон №2" order="2" />          
  </group>     
</ident_list>
XML

  • image — изображение в bm

  • image_scale —  масштабирование изображения.

Касса должна обеспечивать выбор одного конкретного идента из любой группы. Группы могут использоваться только для визуального оформления.
Далее касса вызывает GetCardInfoEx, передает ident code как номер карты. Если используются перекодируемые строковые идентификаторы, то передавать необходимо строковый идентификатор.
Информация о карте, которая была получена при предыдущем запросе вместе со списком идентов, полностью игнорируется. 

Реализация выбора скидки

Если необходимо реализовать на кассе выбор скидки, то необходимо вернуть в список купонов такой список, который позволит внешней системе вернуть в ответ правильную скидку.

Например:

<?xml version="1.0" encoding="utf-8"?>
<ident_list hint="Выберите скидку">
  <group name="group name" printname="Список скидок гостя" order="1">
    <ident code="70589" printname="Белая" order="3" />     
    <ident code="70586" printname="Сиреневая" order="25" default="1"/>            
  </group>
</ident_list>
XML

Автоматическая обработка заказа

Начиная с версии 27, в системе реализована возможность добавления купонов автоматического применения.

В ответ внешняя система должна вернуть OutKind = 3(couponcontent(xml) или OutKind=1 (xml) — для передачи списка блюд для вставки/модификации в ответ на авторизацию.

Внутри тега ident_info, кроме item_content, должен быть подтег item_auto_content, содержащий тэги item той же спецификации, что и подтэги item_content.

<?xml version="1.0" encoding="utf-8"?>
<ident_info>
  <item_auto_content>
      <item line_id="cde05150-15cc-11e5-b939-0800200c9a66" code="123" kind="summ" val="10.00" max="3" default="1" disccode="13"/>     
      <item code="321" kind="percent" val="10.00" max="2" disccode="123"/>            
      <item code="213" kind="price" val="10" max="1"/>                 
  </item_auto_content>
</ident_info>
XML

  • line_id — это GUID строки заказа. Если значение не задано — элементы добавляются иначе, через модификацию исходной строки. Если вы хотите задать атрибут code, то значение должно совпадать с кодом блюда в строке с идентификатором line_id.

  • quant — новое количество.

Все остальные значения — как у ручного купона. 

При автоматическом редактировании заказа также может использоваться модификация заказа.

Повторное получение информации о купонах

При повторном запросе информации о купонах касса передает запрос в FarCards XML, где хранится информация и о примененных купонах. При получении нового списка купонов касса игнорирует, что некоторые купоны уже применялись, и заново проверяет количество купонов.

Система лояльности анализирует XML заказа на предмет наличия примененных купонов и уменьшает лимиты купонов и групп купонов.

Правила применения купонов

Купон не может быть применён к строке с блюдом, если у этого блюда уже есть скидка на блюдо с тем же кодом.

Взаимодействие с модификаторами

Купоны не влияют на модификаторы. То есть к блюду со скидкой по купону может быть добавлен модификатор с ценой.

Купон процентного типа действует только на основное блюдо.

Фиксированная цена — действует только на блюдо до модификаторов.

Взаимодействие с комбо

Купоны не могут применяться комбо-блюдам и комбо-компонентам.

Гашение купона

Реализовывать гашение купона лучше только на транзакции. При этом, при запросе информации о карте, необходимо учитывать количество уже добавленных купонов.

В ситуации, когда применяемый купон запускает процесс приготовления блюд, гости могут потребовать погасить купон в момент включения блюда в заказ. В такой ситуации сторона предоставляющая купон, должна отслеживать текущую ситуацию с купоном и заказом:

  • Первое применение купона:

    • Купон гасится на стороне CRM в момент его включения в заказ

    • Происходит сохранение полученного от кассы xml-чека для последующей идентификации заказа по orderguid.

  • При последующих выборах купона на кассе необходимо:

    • При запросах от других заказов блокировать передачу погашенного купона на кассу

    • При использовании купона в текущем заказе, блокировать передачу погашенного купона на кассу

    • При отсутствии купона в текущем заказе, например, купон по каким то причинам был удален из заказа, разрешить повторную передачу погашенного купона на кассу.

  • При закрытии чека и фиксации транзакций:

    • Подтверждение гашения купона. При закрытии чека необходимо удостовериться в наличии погашенного купона в заказе — сверить заказы по orderguid

    • В случае, если купон был исключен из заказа, — вернуть купон.

  • Возврат купона по timeout — если чек не был закрыт или касса не настроена на пересылку через farcards всех транзакции.

Запрос диалога

Запрос диалога может использоваться для двухступенчатой авторизации — когда гость диктует кассиру код, пришедший в СМС. 

В ответ внешняя система должна вернуть OutKind = 4-ident_list(xml) или OutKind=1 с подтэгом dialog. Если у подтэга dialog заполнен атрибут auto=«1», то диалог вызывается автоматически. Иначе для вызова диалога оператору необходимо ввести код по аналогии со входом в группу купонов.

При наличии диалога с атрибутом auto, остальное содержимое ident_list игнорируется

<?xml version="1.0" encoding="utf-8"?>
<ident_list>
  <dialog auto="1" code="70589" tag="AUTHCODE" caption="Введите код авторизации!" mask="######" prompt="код присылается клиенту в СМС" default=""/>
</ident_list>
XML

  • caption — заголовок диалога или комментарий к полю ввода.

  • prompt — комментарий или подсказка по заполнению, необязательный.

  • mask — маска ввода, Delphi TMaskEdit, необязательный.

  • code — код карты, с которого будет вызван запрос информации о карте после ввода диалога. Если не заполнен, то будет использоваться тот же код, что и в предыдущем вызове. Необязательный параметр.

  • tag — будет занесен в атрибут tag тэга EXTDATA, необязательный.

Касса должна обеспечить отображение диалога.

После успешного ввода касса должна вызвать GetCardInfoEx и передать code, как номер карты. Строка, введенная гостем, передается в атрибуте clientinfoinput тэга EXTDATA. Там же должен быть заполнен атрибут tag, если был заполнен в тэге dialog.

Информация о карте, которая была получена при предыдущем запросе, полностью игнорируется.

Передача URL для отображения

Поддерживается, начиная с версии 38.

Передача URL осуществляется для использования особо сложных форм взаимодействия с системой лояльности.

Внешняя система должна вернуть OutKind = 4-ident_list(xml) или OutKind=1 с подтэгом open_web.

Если у подтэга open_web заполнен атрибут auto=«1», то web-страница откроется автоматически. Иначе для вызова страницы оператору необходимо ввести код по аналогии со входом в группу купонов.

При использовании тэга open_web с атрибутом auto, остальное содержимое ident_list игнорируется.

<?xml version="1.0" encoding="utf-8"?>
<ident_list>
  <open_web auto="1" url="https:\\127.0.0.1\xxxapi\showcardinfo?card=YYYYYY" printname="card=YYYYYY"/>
</ident_list>
XML