Публичное пространство

SetOmni ◾️ API SetOmni

Owned by Артем Кияшко (Unlicensed)
Last updated: авг. 08, 2024 by Ксения Лебедева
20 min read

  • Начиная с версии 10.3.1.0 при включенной опции "Выравнивать размеры скидок в соответствии с требованиями 54-ФЗ" (Лояльность → Общие настройки) в настройках лояльности будет происходить разбиение позиций.

  • При разбиении позиций производится перерасчет номеров всех позиций в чеке и они могут не совпадать с номерами позиций в исходном чеке.

Описание процессов

Методы серверного расчёта скидок позволяют производить их предоставление посредством веб-сервиса для корзин и заказов, оформленных в интернет-магазине, мобильном приложении или ином внешнем по отношению к SetRetail10 сервисе.

Серверный расчёт скидок позволяет произвести:

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

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

  3. Подтверждение транзакции для активации преференций покупателю за оформленный заказ (начисление бонусов).

  4. Отмену расчёта скидок не подтверждённой транзакции (в случае отмены заказа или его изменения).

Описание веб-сервиса

Веб-сервис состоит из методов:

  • doProcessPurchase

  • commitPurchase

  • rollbackPendingTransaction

  • doReturnPurchase

Для работы с серверным калькулятором скидок выполните следующее:

  1. Получите WSDL-структуру веб-сервиса по адресу http://SERVER_IP:8090/SET-ProcessingDiscount/ProcessingPurchaseWS?wsdl.

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

Если нет цели передать необязательные атрибуты, тогда не указывайте эти атрибуты в запросе. Например: нельзя отправить пустой параметр amount="".

Метод doProcessPurchase

Метод doProcessPurchase позволяет:

  • производить расчёт скидок на товары в корзине или оформленном заказе;

  • работать с внутренними картами и купонами.

Существуют два варианта использования этого метода:

  • параметр check отвечает за необходимость сохранения результата расчёта;

  • Проверка:

    • false - метод выполняет предварительный расчёт

    • true - результат расчёта сохраняется в виде транзакции лояльности в БД.

Описание входящих параметров

Поле

Тип данных

Обязательно

Описание

Поле

Тип данных

Обязательно

Описание

Purchase – общие данные чека

id

long

Нет

Идентификатор транзакции (не заполняется при передаче, заполняется Процессингом и только в том случае, если по чеку были какие-либо скидки или операции с бонусными баллами)

shop

long

Centrum - да
Ratail - нет

Номер магазина

number

long

Нет

Номер чека

shift

long

Нет

Номер смены

cash

long

Нет

Номер кассы

amount

double

Нет

Сумма чека (в рублях). Должна равняться сумме стоимости всех позиций в чеке.

discountAmount

Double

Нет

Сумма скидок по чеку

https://crystals.atlassian.net/browse/SR-5612

https://crystals.atlassian.net/browse/CR-7898

10.3.14.0

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:doProcessPurchaseResponse xmlns:ns2="http://listners.discount.crystals.ru/"> <return amount="37.32" discountAmount="4.14" number="123" saletime="2017-06-20T21:56:12.000" shift="1" cash="1" shop="6502"> <position discountable="true" amount="12.81" cost="14.23" count="1.0" goodsCode="00001" departNumber="1" order="1" id="1"/> <position discountable="true" amount="24.51" cost="27.23" count="1.0" goodsCode="00002" departNumber="1" order="2" id="2"/> <advertise operation="accept"> <appliedAction actionGuid="13597" actionName="Безусловная скидка 10%" actionType="DISCOUNT_GOODS"/> <discount posID="1" amount="1.42" quantity="1.0" actionGuid="13597"/> <discount posID="2" amount="2.72" quantity="1.0" actionGuid="13597"/> </advertise> </return> </ns2:doProcessPurchaseResponse> </soap:Body> </soap:Envelope>

saletime

datetime

Да

Дата регистрации чека. Дата и время записываются в формате ISO-8601, пример: 2017-07-20T10:45:15.000+06:00, однако не следует передавать таймзону здесь.

ignoreAdditionalClientCards

boolean

Нет

Игнорировать дополнительные карты/купоны клиента.

https://crystals.atlassian.net/browse/SLS-1242

https://crystals.atlassian.net/browse/CR-5582

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

Важно! Флаг не касается основной карты, номер которой в запросе, только дополнительные карты/купоны.

 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:lis="http://listners.discount.crystals.ru/"> <soapenv:Header/> <soapenv:Body> <lis:doProcessPurchase> <purchase amount="14.23" number="123" saletime="2021-10-05T21:56:12.000" shift="1" cash="1" shop="1328" ignoreAdditionalClientCards="true"> <position discountable="true" amount="14.23" cost="14.23" count="1" goodsCode="00001" departNumber="1" order="1"/> <discountCard cardNumber="22020000"/> </purchase> <check>false</check> </lis:doProcessPurchase> </soapenv:Body> </soapenv:Envelope>

 

Position – данные позиции чека

id

long

Нет

Возвращается номер позиции, если в результате расчета было произведено разделение позиций (не заполняется при передаче, заполняется Процессингом)

goodsCode

string

Да

Код товара

cost

double

Нет

Стоимость единицы товара в данной позиции, используется для расчета скидок (в рублях). Если не указана, то возьмётся из бд Set10.

count

double

Да

Количество товаров в позиции чека, может быть нецелым (для весового товара, например). Десятичный разделитель - точка.

departNumber

long

Да

Номер отдела

order

long

Да

Оригинальный номер позиции в исходном чеке

discountable

boolean

Да

Признак участия товара в расчете скидок. true если участвует и false в противном случае.

positionalActionRestriction – запрет применения определенного типа акций на конкретную позицию

https://crystals.atlassian.net/browse/SR-7175

https://crystals.atlassian.net/browse/CR-10343

10.4.4.0

type

комплексный

Нет

Тип запрета на конкретную позицию товара из корзины.

Возможные значения:

  • DISCOUNTS - запретить применять скидки на позицию (в том числе списание бонусов и электронных фишек)

  • BONUSES_CHARGE_ON - запретить рассчитывать начисление бонусов и электронных фишек

Payment – данные оплат чека

externalCode

string

Нет

Код типа оплаты

paymentType

string

Нет

Не используется, заполнять не требуется

amount

double

Нет

Сумма оплаты данным типом оплат

DiscountCard – данные дисконтных карт и купонов

cardNumber

string

Нет

Номер дисконтной карты или купона

bonusActive

double

Нет

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

bonusTotal

double

Нет

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

amountToWriteoff

double

Нет

Это поле используется и клиентом, и процессингом. В случае, если это поле не задано, при наличии действующей акции "Бонусы как скидка", оно будет заполнено максимальной величиной бонусных баллов, доступных для списания в данном чеке. Если действует та же акция и это поле заполнено клиентом, калькулятор принимает величину в поле amountToWriteoff как величину, которую необходимо списать с бонусного баланса клиента, тем самым применив бонусы как скидку. Если оплата была равна максимальной величине списания бонусов для данного чека, в ответе это поле не возвращается. В противном случае, если оплата оказалась меньше максимальной, возвращается величина баллов, всё ещё доступных для оплаты в данном чеке. Попытка оплатить бонусными баллами величиной большей, чем максимально допустимая, приведёт к ошибке.

notAppliedReason

string

Нет

Заполняется только процессингом и только в случае, если переданный купон или карта не участвовали в расчете скидок. Если это поле не заполнено, купон или карта участвовали в расчете скидок. Поле принимает фиксированный диапазон значений:

USED - купон уже был использован и потому не применён;

INACTIVE - срок действия карты или купона ещё не начался;

EXPIRED - срок действия карты или купона истёк;

NOT_FOUND - карта или купон не найдены;

DOES_NOT_FIT - карта или купон не применены, поскольку не соблюлись условия действия рекламной акции, использующей данную карту или купон;

MORE_PROFITABLE_DISCOUNT_APPLIED - карта или купон не была применена, поскольку сработала рекламная акция, несущая большу́ю скидку;

BLOCKED - карта заблокирована;

OTHER - все остальные причины, не перечисленные здесь. При нормальной работе вы не должны увидеть эту причину неприменения.

validThrough

Date

Нет

Заполняется только процессингом и только в случае, если карта или купон не применены по причинам DOES_NOT_FIT или MORE_PROFITABLE_DISCOUNT_APPLIED. Поле не заполняется при условии, если купон действует бессрочно. Отображает дату, до которой действует карта или купон.

clientDecision – решение покупателя о применении акции

https://crystals.atlassian.net/browse/SR-5928

https://crystals.atlassian.net/browse/CR-11099

10.4.4.0

actionGuid

Long

Да

Идентификатор акции

decisionValue

Комплексный

Да

Решение о применении акции

  • APPLY - применять акцию

  • REFUSE - не применять акцию

Пример вызова метода

В исходном чеке должен быть как минимум один элемент position.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:lis="http://listners.discount.crystals.ru/"> <soapenv:Header/> <soapenv:Body> <lis:doProcessPurchase> <purchase amount="41.46" number="123" saletime="2017-06-20T21:56:12.000" shift="1" cash="1" shop="6502"> <position discountable="true" amount="14.23" cost="14.23" count="1" goodsCode="00001" departNumber="1" order="1"/> <position discountable="true" amount="27.23" cost="27.23" count="1" goodsCode="00002" departNumber="1" order="2"/> </purchase> <check>false</check> </lis:doProcessPurchase> </soapenv:Body> </soapenv:Envelope>

Возвращаемые параметры

Поле или структура

Тип данных

Описание

Поле или структура

Тип данных

Описание

advertise – данные рассчитанных РА

operation

String

Признак проведения операции расчета РА (accept– успешно, reject– неуспешно)

reason

String

Описание причины неуспешного проведения операции расчета. Актуально при operation = ‘reject’

customer – данные о владельце Внутренних карт

id

Long

Идентификатор клиента

clientName

String

Имя владельца ДК

card

String

Номер Внутренней карты

appliedAction – описание примененных в чеке рекламных акций

actionType

Комплексный

Тип скидки

  • DEFAULT - другое

  • SET_GOODS - товарный набор

  • DISCOUNT_GOODS - скидка на товары

  • SECOND_PRICE - вторая цена (на самом деле: "цена из справочника")

  • DISCOUNT_CARD - скидка по карте

  • FIX_PRICE - фиксированная цена

  • DISCOUNT - денежная сидка

  • https://crystals.atlassian.net/browse/SR-4870

actionName

String

Название акции

actionGuid

Long

Идентификатор акции

externalCode

String

Идентификатор акции в внешней системе

dateStart

Datetime

Дата и время начала действия рекламной акции

dateFinish

Datetime

Дата и время окончания действия рекламной акции. null, если акция действует бесконечно

appliedCard – описание карт и купонов, по которым сработала описываемая акция (если акция действует не по карте, блок не заполняется)

cardType

String

Тип карты (InternalCard – внутренняя дисконтная карта, ExternalCard - внешняя карта, Coupon – купон)

cardNumber

String

Номер карты

actionLabels – метки рекламной акции

https://crystals.atlassian.net/browse/SR-7018

https://crystals.atlassian.net/browse/CR-9324

10.4.2.0

  • label

String

Метка рекламной акции

discount – данные о рассчитанных в чеке скидках

posID

Integer

Номер позиции, на которую применена скидка. Если 0 – скидка применена на весь чек

amount

Long

Сумма скидки

actionGuid

Long

Идентификатор РА (описание акции в секции appliedAction)

quantity

Integer

Количество товара, на которое применена скидка

bonus – данные о бонусных операциях

bonusValue

Double

Количество начисленных баллов в "рублях"

card

String

Номер карты, на которую начислены баллы

firstDate

Datetime

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

lastDate

Datetime

Дата окончания действия начисленных баллов (не заполняется, если начисленные бонусы действуют бессрочно)

accountTypeCode

Long

Код типа бонусного счета

actionGuid

Long

Идентификатор РА (описание акции в секции appliedAction)

bonusPosition – информация о том, как распределились бонусы по позициям

bonusValue

Double

Количество бонусов. Если начисленные бонусы, то значение больше нуля. Если списанные - меньше

posID

Integer

Номер позиции, на которой распределились бонусы

сообщения кассиру и покупателю

cashiermessage

String

Сообщение кассиру

customermessage

String

Сообщение покупателю

coupons – список купонов, которые являлись результатом применения рекламной акции

barcode

String

Баркод купона. Заполняется только при операции commit. При операции doProcessDiscount с параметром check=true, даже если результатом применения рекламной акции был купон, его номер не показывается, поскольку на этом этапе ещё можно отменить транзакцию. Выполнение операции commit означает, что транзакция завершена, заказ оплачен и только тогда пользователь может получить номер купона, который можно использовать.

title

String

Название купона. Купон может не иметь названия.

description

String

Описание купона. Купон может не иметь описания.

activationDate

Datetime

Дата и время без учета таймзоны, при наступлении которой купон становится активным. null, если становится активным сразу по выдаче.

expirationDate

Datetime

Дата и время без учета таймзоны, по истечении которой купон перестаёт быть активным. null, если купон бессрочный.

discount

Long

(только для скидочных купонов) Величина скидки, которую предоставляет этот купон. Единицы величины описываются полем type купона.

maxDiscount

Long

(только для скидочных купонов) Максимальная величина скидки, которую предоставляет этот купон.

type

String

(только для скидочных купонов) Тип скидки купона. Возможные значения:

PERCENT - означает, что скидка предоставляется в процентах.

FIXED_SUM - фиксированная величина скидки в минимальных денежных единицах.

CALCULATED - скидка расчитывается по чеку.

category

String

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

UNIQUE - несерийный купон однократного применения.

DISCOUNT - скидочный купон.

OTHER - иной тип купона, не попавший под остальные типы. Используется, когда выдаваемый купон выдаётся просто в виде штрих-кода, без указания категории или типа купона.

actionGuid

Long

Guid акции, результатом которой стала выдача этого купона.

notAppliedAction – акции, которые не применились в чеке из-за срабатывания ограничения

https://crystals.atlassian.net/browse/SR-7018

https://crystals.atlassian.net/browse/CR-9324

10.4.2.0

actionGuid

Long

Идентификатор акции

actionName

String

Название акции

actionType

Комплексный

Тип скидки

  • DEFAULT - другое

  • SET_GOODS - товарный набор

  • DISCOUNT_GOODS - скидка на товары

  • SECOND_PRICE - вторая цена (на самом деле: "цена из справочника")

  • DISCOUNT_CARD - скидка по карте

  • FIX_PRICE - фиксированная цена

  • DISCOUNT - денежная сидка

  • BONUSES - списание/начисление бонусов

  • STAMPS - списание/начисление фишек

externalCode

String

Идентификатор акции в внешней системе.

dateStart

Datetime

Дата и время начала действия рекламной акции

dateFinish

Datetime

Дата и время окончания действия рекламной акции. null, если акция действует бесконечно.

appliedLoyaltyRestriction – текущее ограничение по покупателю, установленное в рамках рекламной акции

https://crystals.atlassian.net/browse/SR-7018

https://crystals.atlassian.net/browse/CR-9324

10.4.2.0

limit

Integer

Остаток по лимиту для покупателя

expireDate

Datetime

Дата и время ближайшего обновления лимита

position – дополнительные возвращаемые значения в позиции

nds

Double

Ставка НДС по позиции

ndsSum

Double

Сумма НДС по позиции

amount

Double

Итоговая стоимость позиции (в рублях)

costWithDiscount

10.3.1.0

https://crystals.atlassian.net/browse/SR-4903

https://crystals.atlassian.net/browse/CR-5854

Double

Цена товара с учетом всех скидок.

Пример запроса:

Пример ответа на этот запрос с указанием параметра:

discountable

Boolean

Применена скидка

cost

Double

Стоимость позиции

count

Double

Количество товара в позиции

departNumber

Integer

Номер отдела

goodsCode

String

Код товара

id

Integer

Код позиции в строке

order

String

Номер заказа

Примера ответа на этот вызов (на сервере была заведена безусловная акция со скидкой 10% на все товары)

Учет скидки по сроку годности

https://crystals.atlassian.net/browse/SR-4685

https://crystals.atlassian.net/browse/CR-5394

10.2.97.0

Атрибут добавляется в блок позиций чека в методе doProcessPurchase, для возможности передачи срока годности конкретной позиции в SetOmni и расчёта скидки по сроку годности.
Данный атрибут должен быть также указан в возвращаемом блоке позиций для рассчитанного чека.

  • Блок размещения: Position

  • Название поля: expirationDate

  • Тип поля: datetime

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

  • По умолчанию: атрибут отсутствует

  • Формат: 'YYYY-MM-DDTHH:MM:SS.ZZZ'

    • Варианты указания даты:

      • без секунд, YYYY-MM-DDTHH:MM:00.000'

      • без времени, YYYY-MM-DDT00:00:00.000'

  • Описание: Дата и время окончания срока годности товара - всего количества товара в позиции. Используется для запрета продажи а также для расчёта скидки по сроку годности

Пример запроса с указанием параметра:

Пример ответа с с указанием параметра:

Принцип - алгоритм работы с данным атрибутом:

  • В поле expirationDate может быть указана только дата или дата со временем.

  • Если для позиции указана дата окончания срока годности, то по данной позиции необходимо рассчитать скидку по сроку годности, если действует такая рекламная акция.
    Информацию о самой акции необходимо указать в соответствующем блоке advertise, appliedAction и discount

  • Если для позиции указана дата окончания срока годности не указана, то данная позиция не участвует в расчёте скидок по сроку годности.

  • Если указана не корректная дата окончания срока, дата указана не по формату, то необходимо вернуть ошибку указания данных в блоке Fault с указанием соответствующей ошибки.
    Например “Дата окончания срока годности задана не корректно“, и далее в блоке faultgood перечислить коды товаров из позиций для которых дата задана не корректно.

Пример ошибки:

  • Если для позиции указана дата окончания срока годности в прошлом, относительно момента запроса, то такая позиция участвует в расчёте всех остальных скидок, кроме скидки по сроку годности. продажа такого товара не запрещена, так как запрет продажи просроченного товара лежит на кассовой программе.

Ограничения

  1. Контроль самого срока годности лежит на кассовой части реализации, т.е. в запросе не должны быть товаров у которых срок годности в прошлом. Для таких товаров скидка по сроку годности рассчитана не будет, но будут рассчитаны другие скидки, и товар не будет удалён из чека или как-то помечен, что он просрочен!

  2. Необходимо понимать что если на товаре дата указана в виде “2021-01-10”, то это означает срок годности до 10-го января включительно,
    и соответственно у товара срок годности заканчивается после 2021-01-10 23:59:59.999, т.е. в запросе у позиции должна быть указана дата в полном формате:
    expirationDate = “2021-01-10T23:59:59.999“ или начало следующего дня “2021-01-11T00:00:00.000“

Срабатывание ограничения по акции

https://crystals.atlassian.net/browse/SR-7018

https://crystals.atlassian.net/browse/CR-9324

10.4.2.0

Для передачи информации о действующих ограничениях по рекламным акциям в секцию advertise добавлен элемент appliedLoyaltyRestriction, а также элемент notAppliedAction для указания акций, которые не сработали из-за превышения покупателем заданного ограничения.

Пример запроса:

Пример ответа:

Запрет на расчет скидок и начисление бонусов

https://crystals.atlassian.net/browse/SR-7175

https://crystals.atlassian.net/browse/CR-10343

10.4.4.0

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

Возможные типы запрета:

  • positionalActionRestriction type="DISCOUNTS" - запрет на применение скидок на позицию (включает в себя списание бонусов и фишек);

  • positionalActionRestriction type="BONUSES_CHARGE_ON" - запрет расчета начисления бонусов и электронных фишек.

Новый признак дополняет уже существующий признак discountable (признак участия товара в расчете скидок - true, если участвует, и false в противном случае).

Атрибуты у позиции

Действие системы с позицией из корзины

Атрибуты у позиции

Действие системы с позицией из корзины

1

  • discountable = "true"

  • positionalActionRestriction type="DISCOUNTS"

  • Запрещено применять скидки на позицию

  • Разрешено рассчитывать начисление бонусов, фишек

2

  • discountable = "true"

  • positionalActionRestriction type="BONUSES_CHARGE_ON"

  • Разрешено применять скидки на позицию

  • Запрещено рассчитывать начисление бонусов и фишек

3

  • discountable = "true"

  • positionalActionRestriction не задан или пустой

Рассчитаются все доступные типы механик (скидки, начисление бонусов и фишек) для позиции

4

  • discountable = "false"

  • positionalActionRestriction - любое из передаваемых значений (BONUSES_CHARGE_ON, DISCOUNTS)

Позиция не участвует в расчете скидок

Пример запроса

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

Ограничения

Прочие результаты расчета корзины (выдача купонов, информационные сообщения кассиру/покупателю) будут рассчитаны системой вне зависимости от значений атрибутов discountable, positionalActionRestriction , поскольку эти результаты создаются на корзину целиком, а не на конкретные позиции.

Применение скидки по решению покупателя