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

SetOmni ◾️ API SetOmni

Owned by Артем Кияшко (Unlicensed)
Last updated: авг. 11, 2022 by Парень Александр
16 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

Вместе с основной картой клиента приходят и его купоны, флаг со значением 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 в противном случае.

costWithDiscount

10.3.1.0

Double

Да

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

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. Поле не заполняется при условии, если купон действует бессрочно. Отображает дату, до которой действует карта или купон.

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

В исходном чеке должен быть как минимум один элемент 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

String

Тип скидки

  • DEFAULT - другое

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

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

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

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

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

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

    • 10.2.99.0

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

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

actionName

String

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

actionGuid

Long

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

externalCode

String

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

dateStart

Datetime

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

dateFinish

Datetime

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

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

cardType

String

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

cardNumber

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 акции, результатом которой стала выдача этого купона.

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

nds

Double

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

ndsSum

Double

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

amount

Double

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

discountable

Boolean

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

cost

Double

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

count

Double

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

departNumber

Integer

Номер отдела

goodsCode

String

Код товара

id

Integer

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

order

String

Номер заказа

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

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

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“

Метод commitPurchase

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

Пример подтверждения транзакции

transactionId берется из атрибута id поля return ответа метода doProcessPurchase, в данном случае он равен 148. Ответ должен вернуться вида

В случае, если результатом действия РА являлись купоны, их баркод и тип будет сообщен клиенту на этапе коммита транзакции:


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

Метод rollbackPendingTransaction

Метод позволяет отменить транзакцию лояльности, созданную ранее в ходе расчёта скидок, но не подтверждённую.

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

Метод doReturnPurchase

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

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

Где:

Наименование атрибута

Тип данных

Обязательно

Описание

Наименование атрибута

Тип данных

Обязательно

Описание

id

Long

Да

Идентификатор транзакции лояльности

goodsCode

String

Нет

Артикул товара. Обязателен при возврате позиций

count

Double

Нет

Количество товара в ед.изм. Обязателен при возврате позиций

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

Пример

Метод doProcessPurchase

 

 

Возможные варианты работы с  API серверного расчета скидок

1. Скидка на товарный набор (фиксированная цена)

Создаем РА, в результате которой у товарного набора будет фиксированная цена, например, 100р.

Товарный набор состоит из товаров 00044 и 00055

Посылаем запрос вида

Получаем ответ вида

2. Расчет скидок с учетом заданного магазина

  • Создаем безусловную рекламную акцию:

  • Скидка 5% на весь товарный справочник с зоной охвата магазин 99.

  • Посылаем запрос на расчет скидок с указанием номера магазина 1 (shop="1")

  • Проверяем, что на товары НЕ предоставилась скидка

  • Изменяем в запросе на расчет скидок номер магазина на 99 и повторно посылаем запрос

  • Проверяем, что на товары предоставилась скидка 5%

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

3. Расчет скидок на указанную дату и времени

  • Создаем безусловную рекламную акцию: скидка 10% на весь товарный справочник с окончанием срока действия через месяц от текущей даты (сегодня 20.04.2017 , срок окончания действия РА 20.05.2017 00:00)

  • Посылаем запрос на расчет скидок с указанием даты 21.05.2017

  • Проверяем, что на товары скидка не предоставлена

  • Посылаем запрос на предварительный расчет скидок с указанием даты 19.04.2017

  • Проверяем, что на товары скидка не предоставлена

  • Посылаем запрос на предварительный расчет скидок с указанием даты 25.04.2017

  • Проверяем, что на товары предоставилась скидка 10%

4. Расчет бонусов для списания

  • На сервере должна быть бонусная карта с активными бонусами. Создаем РА на списание бонусных 99% баллов с этой категории карт.

  • Посылаем запрос на предварительный расчет скидок с указанием номера внутренней карты

  • Проверяем, что предоставилась информация о возможности списать бонусы в количестве 99% баллов от суммы товара

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

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


5. Расчет бонусов для начисления

  • Создаем РА на начисление 100 бонусных баллов при применении карты.

  • Посылаем запрос на расчет скидок с указанием номера внутренней карты

  • Проверяем, что отобразилась информация о начисленных бонусах в кол-ве 10% от суммы чека

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

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

На карте было 1000 бонусов, начислили сверху 100

Если нужен не просто расчет, а реальное начисление бонусов, необходимо подтвердить транзакцию вызовом метода commitPurchase. Необходимо обратить внимание, что у атрибута check состояние true.

6. Расчёт скидок без указания цены

Если необходимо, чтобы цена товаров использовалась из SetRetail10, то в позициях не надо передавать cost.

Цены должны быть загружены на SetRetail. Если это условие нарушено, то будет следующая ошибка:

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

7. Отмена начислений бонусов

  • Создаем РА на начисление 100 бонусных баллов при применении карты.

  • Посылаем запрос на расчет скидок с указанием номера внутренней карты

  • Проверяем, что отобразилась информация о начисленных бонусах в кол-ве 100 баллов. Проверяем, что в БД в таблице loy_transaction появилась новая транзакция со статусом отправки на сервер = 6 и статусом транзакции = 0.

  • Посылаем запрос на отмену расчета скидок с указанием номера транзакции

В результате транзакция лояльности целиком удаляется из базы.

Потоварный учёт начисленных и списанных бонусов

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

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

Информация о начисленных/списанных бонусах хранится в bonusPosition, который находится внутри bonus.





© 1994-2023, ООО «Кристалл Сервис Интеграция».
Все права защищены..

Политика обработки персональных данных