Техническое задание по интеграции с киосками самообслуживания

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

Процесс работы интегрированного киоска с UDS:

1. Клиент скачивает приложение UDS

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

3. В окне ввода бонусной карты есть возможность ввода кода (6 цифр, 8 цифр) из приложения UDS App или код виртуальной карты, а такжетак же ввести номер телефон (дополнительная возможность, по коду основное). Или можно использовать сканер QR кодов в киоске

4. После ввода кода отображается окно с ФИО клиента, его статус, баланс баллов и кнопки Списать баллы или Начислить

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

6. После выбора “Списать” итоговая сумма счета понижается на количество списываемых бонусов. Например, счет 100, списываем 30 бонусов, итого клиент должен оплатить 70 рублей

7. После оплаты в UDS отправляется информация о данной оплате

8. Если по каким-то причинам чек был проведен без использования UDS, то реализовать отображение ваучера для накопления бонусов после покупки.

Ниже описано более подробно и с методами

Предполагаемый бизнес процесс работы киоска с UDS:

1. В окне где показан итоговый счет к оплате добавляется кнопка “Бонусы UDS”

2. При нажатии этой кнопки отображается окно со следующем текстом:

“С бонусами выгоднее. Скачайте приложение UDS и введите код клиента (6 или 8 цифр)”

Ниже есть поле для ввода кода клиента и зеленая кнопка рядом “Ок”.

Еще ниже есть неакцентная кнопка “Нет приложения. Накопить по номеру телефона”

3. Клиент вводит код или номер телефона и нажал ОК

После ввода кода (6 цифр из приложения) отправляется запрос в UDS (get запрос find customer, см. документацию docs.uds.app):

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

curl -H 'Accept: application/json' \
-H "X-Origin-Request-Id: $(uuidgen)" \
-H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
-u "<companyId>:<api_key>"
-X GET -s https://api.uds.app/partner/v2/customers/find?code=456123&exchangeCode=true&total=1000&skipLoyaltyTotal=100&unredeemableTotal=200

или  -X GET -s https://api.uds.app/partner/v2/customers/find?phone=%2B79275551122&total=1000&skipLoyaltyTotal=100&unreedemableTotal=200

где code - код клиента из мобильного приложения UDS,

phone- номер телефона клиента в международном формате, вместо “+” отправляется “%2B”.

total - изначальная сумма счета (без скидок и списанных бонусов)

exchangeCode - запрос на получение кода клиента длительностью 24 часа (вместо кода из приложения, у которого время действия 45 минут);

skipLoyaltyTotal – сумма, на которую не должна применяться прямая скидка (данный параметр влияет в этом запросе, если в компании установлена настройка "Предоставление скидки", а не начисление бонусных баллов).

unredeemableTotal - сумма чека, на которую запрещено списывать бонусы. В этом случае максимальное количество баллов будет рассчитано с учетом этого параметра

Возвращается ответ, основные поля:

uid - идентификатор пользователя (по нему также можно производить поиск и оплату)

displayName- имя и фамилия,

membershipTier: name- статус клиента в программе лояльности,

discountRate- процент скидки у клиента,

cashbackRate - процент начисления бонусов у клиента,

points- количество баллов

maxPoints- количество допустимых к списанию баллов (рассчитывается исходя из поля total)

code- код для проведения в дальнейшем транзакции (если запрос осуществлялся по номеру телефона, то вернется пустое поле)

И на экране отображается информация о клиенте:

• ФИО (displayName)

• Статус клиента (membershipTier: name)

• Баланс (points)

• Доступно к списанию (maxPoints)

• И две кнопки Списать (отображать, если maxPoints>0) или Начислить

Внимание! Если при вводе кода вернулась ошибка 404 notFound, то показать пользователю ошибку “Неверно введен код. Посмотрите пожалуйста его в приложении UDS”

Если клиент выбрал Списать, то открывается окно для ввода количества списываемых бонусов, в котором указано доступное количество бонусов для списания, это значение можно изменить в меньшую сторону с помощью клавиатуры.

Если клиент выбрал Начислить, то к данному заказу просто прикрепляется карта клиента /номер телефона (это можно как-то визуально показать) и после оплаты будут начислены баллы

4. Если discountRate не равно нулю, то к заказу применяется указанная в этом параметре процентная скидка, например 10% (скидка применяется к товарам в чеке, кроме товаров, на которые запрещено предоставлять скидку - сумма таких товаров передается в параметре skipLoyaltyTotal)

Важно! Применение скидки допустимо только при вводе кода из приложения, при вводе номера телефона скидка не должна применяться.

5. Если клиент списывает бонусы, итоговая сумма счета уменьшается на количество списываемых баллов (1 балл= 1 рубль скидки). В случае накопления бонусов сумма счета не изменяется

6. После нажатия кнопки Оплатить (закрытия заказа) и прихода успешного статуса от эквайринга об оплате, транзакция должна отправиться и в UDS (Create operation, см. документацию docs.uds.app).

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

curl -H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Origin-Request-Id: $(uuidgen)" \
-H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
-u "<companyId>:<api_key>"
-d '{ \
"code":"string", \
"participant":{ \
"phone":"string"
},\
"nonce":"string-UUID", \
"cashier":{ \
"externalId":"string", \
"name":"string" \
}, \
"receipt":{ \
"total":100.0, \
"cash":50.0, \
"points":50.0, \
"number":"string", \
"skipLoyaltyTotal":null \,
"unredeemableTotal":null \
} \
}' -X POST "https://api.uds.app/partner/v2/operations"

В запросе Create operation передаются следующие параметры:

• code (код для проведения транзакции, из ответа к запросу Find customer) или phone (номер телефона в международном формате через +7)

• total (изначальная сумма счета, в том числе и акционные товары)

Если в заказе присутствуют сторонние скидки, тогда сумма total должна высчитываться по следующему правилу: total= изначальная сумма счета - (сторонняя скидка* изначальная сумма счета)

• points (количество списываемых баллов у клиента), если оплата оплата без списания бонусов, то указать 0cash (сумма оплаченная деньгами (карта или наличкой или комбинированная оплата))

• externalId и name идентификатор и имя киоска, на котором производилась оплата. В кассовой системе этим идентификатором может являться id или номер киоска

• number (номер чека в кассовой системе)

• skipLoyaltyTotal (сумма стоимости товаров, на которую не должны начисляться и списываться бонусы и не должна применяться скидка UDS. Например, сумма акционных товаров)

• nonce - произвольная строка вида uuid, которая может быть использована только однажды. Рекомендуется указывать для исключения повторных операций в случае дублирования запроса.

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

Внимание! Списываемые баллы не должны попадать в прибыль. Т.е по списанным баллам не должны взыматься налоги. Баллы должны применяться как скидка в цене товара

7. Возможные ошибки при отправке запроса в UDS об оплате

Статус	Код ошибки	Описание
400	badRequest	Form validation errors occurred. Неверно сформирован запрос
400	invalidChecksum	Неправильно переданы значения в параметрах total, points и cash. Запрос не прошел проверку контрольной суммы
400	insufficientFunds	Попытка списания баллов больше чем есть у клиента на балансе.
400	discountLimitExceed	Попытка списания баллов больше чем допустимо по маркетингу. Например, можно списать только 50% баллами со счета, а пытаются списать больше
401	unauthorized	Компания не активна или некорректно указаныAPI Key и ID компании
404	notFound	Неверно введен код клиента или время жизни кода истекло. Введите пожалуйста новый код
404	cashierNotFound	Идентификатор в cashierExternalId недопустим. Принимаются только цифры и латинские буквы без пробелов

8. Реализовать возможность отмены оплаты. Т.е. при отмене в учетной системе также должна происходить отмена транзакции в UDS. Запрос https://api.uds.app/partner/v2/operations/<id>/refund , где id - это id транзакции UDS, значение которой возвращается ответом после успешной проведенной транзакции.

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

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

curl -H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Origin-Request-Id: $(uuidgen)" \
-H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
-u "<companyId>:<api_key>"
-d '{ \
"partialAmount":100.0 \
}' -X POST "https://api.uds.app/partner/v2/operations/<id>/refund"

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

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

Метод позволяет отобразить на экране или напечатать на чеке код ваучера (qr код) и клиент, отсканировав его в приложении UDS App, сможет получить баллы за покупку. Ваучер должен запрашиваться только если к заказу не применялась программа лояльности UDS для избежания двойных начислений бонусов. Срок жизни ваучера - 3 часа.

Важно! Обязательным условием использования данного функционала является настройка модуля программы лояльности “Начислять бонусные баллы” в блоке настройки “Способ предоставления скидки” UDS Business, а также процент начисления бонусов для базового статуса должен быть больше 0

Создание ваучера на проведение операции в UDS. В случае успеха вы получите информацию для печати кода и ссылки на графическое отображение QR кода ваучера на чеке или экране.

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

curl -H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Origin-Request-Id: $(uuidgen)" \
-H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
-u "<companyId>:<api_key>"
-d '{ \
"nonce":"string-UUID", \
"cashier":{ \
"externalId":"string", \
"name":"string" \
}, \
"receipt":{ \
"total":100.0, \
"number":"string", \
"skipLoyaltyTotal": null \
} \
}' -X POST "https://api.uds.app/partner/v2/operations/voucher"

В запросе Voucher передаются следующие параметры:

• total (изначальная сумма счета); Если в заказе присутствуют сторонние скидки, тогда сумма total должна указываться после применения этих скидок.

• skipLoyaltyTotal – сумма, на которую не должны начисляться бонусы. Если в заказе присутствуют товары, которые не должны участвовать в системе UDS (т.е. на эти товары не распространяются скидки), то нужно передать в этом поле их сумму.

• externalId и name - идентификатор и имя киоска, на котором производилась оплата. В кассовой системе этим идентификатором может являться id или номер киоска

• number (номер чека в кассовой системе)

Ответ на запрос создания ваучера, основные поля

• code - Числовой код ваучера

• qrCodeText - Текст для самостоятельной генерации QR - кода ваучера для дальнейшей печати или отображения на экране

• qrCode256 - Ссылка на картинку QR кода (size 256), которую можно распечатать или отобразить.

• expiresIn - Время, когда ваучер сгорит по UTC

• points - Количество баллов для начисления. Рассчитывается из настроек базового уровня бонусной программы. Если клиент с повышенным статусом отсканирует чек, то бонусы будут начислены согласно статусу клиента

Чрезвычайные ситуации

1. Если оплата в киоске прошла (в том числе и по эквайрингу), а в UDS не прошла, вернулась какая-то ошибка, то для пользователя ничего не нужно показывать. Нужно сохранить информацию об этой оплате в какой-то документ (логи). По данным транзакциям оплаты в UDS будут проведены вручную.
   Необходимая информация об неуспешной транзакции UDS:

• код клиента или номер телефона

• ФИО клиента

• Дата и время транзакции

• Суммы total, points и cash

• ExternalId и name идентификатор и имя кассира (киоска)

1. Если оплата в UDS прошла, но заказ в киоске по каким-то причинам не закрылся и клиент в итоге не совершил покупку, то необходимо отправить в UDS команду на отмену операции (п.8). Нужно сохранить информацию об этой оплате в какой-то документ (логи). По данным транзакциям оплаты в UDS будут проведены вручную.
   Необходимая информация об неуспешной транзакции UDS:

• код клиента или номер телефона

• ФИО клиента

• Дата и время транзакции

• Суммы total, points и cash

• ExternalId и name идентификатор и имя кассира (киоска)