Техническое задание по интеграции интернет­-магазина с UDS

Описание API методов доступно по ссылке: docs.uds.app

Примеры запросов в Partner API 

Весь бизнес-процесс по работе с интернет-магазином остается прежним. Изменения, касающиеся интеграции с UDS, необходимо будет применить к Корзине интернет-магазина и выдаче заказа. Модуль должен настраиваться без привлечения специалистов, id компании и API Key из UDS Бизнес, код приглашения, тексты в корзине указываются в настройках модуля. Комментарии об ошибках, списании/начислении баллов должны поддерживать многоязычность

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

1. Администратор сайта может установить модуль самостоятельно, указать необходимые настройки для доступа к API UDS, текст для отображения клиентам, qr код и ссылку на вступление в компанию UDS.

2. Клиент скачивает приложение UDS App и вступает в компанию.

3. Вводит код из приложения или номер телефона в корзину интернет-магазина.

4. Отображается информация о клиенте (Имя, Фамилия, сколько баллов накопил). Если клиент вводил номер телефона, но он в системе не зарегистрирован, то выводить информацию, что баллы будут начислены по номеру телефона и ссылка на скачивание приложения.

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

6. Клиент вводит сколько бонусов списать, 1 балл = 1 рубль. 

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

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

Важно! Информация об операции отправляется сразу в UDS после создания заказа, поэтому в настройках программы лояльности необходимо установить отложенное начисление баллов (от 1 до 15 дней в зависимости от срока исполнения заказа) 

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

1. В корзину интернет-магазина добавить поле Промо­код UDS и возможность ввода кода клиента из мобильного приложения UDS или номера телефона клиента в международном формате +79992221133

2. После нажатия “Получить скидку” отправляется GET запрос в UDS и отображается информация о клиенте (get запрос find customer, см. документацию 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=300&unredeemabletotal=100

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

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

skipLoyaltyTotal - сумма, на которую не должна применяться скидка или начисляться баллы 

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

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

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

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

Если в заказе присутствуют товары, на которые не должны списываться баллы, тогда сумма этих товаров должна передаваться в поле unredeemableTotal= сумма товаров, на которую не списываются баллы

Ответ, основные поля:

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

user -> displayName - имя и фамилия 

user -> participant -> discountRate - размер скидки

user -> participant -> points - количество баллов на балансе

purchase -> maxPoints - суммарное количество допустимых к списанию баллов

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

user -> participant -> id – идентификатор клиента в этой компании (нужен для понимания вступил ли клиент в компании.)

Если запрос был по коду и в ответ приходит ошибка 404 notFound, ты выводить сообщение, что неверно указан код из приложения UDS App и необходимо ввести новый код.

Если клиент не вступил в компанию (user -> participant -> id=null), то можно вывести информацию об этом, ссылку на вступление и qr код

• Применение скидки к заказу

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

3. Применяется скидка к заказу в размере discountRate. Если discountRate = 0, то это значит, что клиенту после оплаты будут начислены бонусы и скидка не нужна.

Если discountRate > 0, то к заказу должна применяться скидка, процент которой приходит в этом параметре. В этом случае сумма счета сначала уменьшается на процент скидки, а после клиенту предлагается списать/ накопить бонусы.

• Списание бонусных баллов

Важно! Списание бонусов всегда доступно при вводе кода из приложения. По номеру телефона бонусы можно списывать при условии, что в компании активна соответствующая настройка. По uid нельзя списывать бонусные баллы, только копить. Для определения Возможности списания баллов и их количество необходимо ориентироваться на параметр purchase -> maxPoints  из ответе  при поиске клиента

4. После этого должно отобразиться поле “Списать баллы”, в котором вводится количество баллов для списания (не больше maxPoints). Если значение параметра maxPoints  равно 0, то ввод количества списываемых баллов должен быть недоступен.

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

Важно! Если по каким-то причинам корзина изменилась после указания суммы к списанию, то нужно повторно отправлять запрос find, чтобы клиент не смог после редактирования корзины списать баллов больше, чем можно по ограничениям

6. После нажатия “Сделать заказ” переходим на форму оплаты оставшейся суммы и оформления доставки

7. После отправления заказа необходимо отправить запрос в UDS о проведении транзакции (Create operation, см. документацию docs.uds.app).

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

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

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", \
  "nonce":"string", \
  "cashier":{ \
    "externalId":"string", \
    "name":"string" \
  }, \
  "receipt":{ \
    "total":100.0, \
    "cash":0.0, \
    "points":100.0, \
    "number":"string", \
    "skipLoyaltyTotal ":10.0, \
    "unredeemableTotal":100.0 \
  } \
}' -X POST "https://api.uds.app/partner/v2/operations"

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

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

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

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

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

• points (количество списываемых баллов у клиента);

• cash (сумма, оплаченная деньгами: карта, наличными или комбинированная оплата);

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

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

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

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

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

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

Если в заказе присутствуют товары, на которые не должны списываться баллы, тогда сумма этих товаров должна передаваться в поле unredeemableTotal= сумма товаров, на которую не списываются баллы.

Для списания бонусов без начисления баллов необходимо передавать запрос Create operation со следующими значении: skipLoyaltyTotal = cash. 

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

8. Если при проведении транзакции Create operation вернулась ошибка от UDS, то необходимо в консоли администратора интернет-магазина сделать какое-либо оповещение, что по данному заказу не произошла транзакция по UDS

Возможные ошибки:

9. Реализовать возможность отмены оплаты. Т.е. при отмене заказа в интернет-магазине, также должна происходить отмена транзакции в 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"

Необходимые данные, которые нужно будет хранить на стороне интеграционного модуля:

• После получения информации от UDS, что оплата прошла успешно, сохранить id операции и привязать ее к заказу для возможности отправки возврата