RUS
  • ENG
  • RUS

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

Последние изменения: 06.03.2024

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

Логическая схема запросов

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


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

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

  2. Показывает свой код из приложения кассиру

  3. Кассир вводит данный код в кассу и отображается информация о клиенте (Имя, Фамилия, сколько баллов накопил)

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

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

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

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

  8. Реализовать возможность отмены оплаты, т.е. при отмене в учетной системе также должна происходить отмена транзакции в UDS

 

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

 

Требования: 

  • API key (токен) и id компании, которые мы используем при интеграции с кассой, не должны жестко прописываться в коде. Т.е. при настройке интеграционного модуля должна быть возможность прописать API key и id в какой-нибудь конфигурационный файл (config), т.к. они для каждой компании свой 

Внимание! Если при отправке запросов возвращается 403 ошибка forbidden, то API key или id компании введены неверно

 

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



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

1.  После формирования итогового счета к оплате должна быть возможность ввода кода клиента из мобильного приложения UDS promo.uds.app или номера телефона клиента в международном формате +79992221133. Если есть возможность, так же реализовать ввод кода клиента с помощью сканера QR кодов

 

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

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

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

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

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

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

 

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

• uid - идентификатор пользователя (по uid также можно производить поиск и оплату),
• displayName - имя и фамилия,
• discountRate - размер скидки,
• points - количество баллов,
• maxPoints - количество допустимых к списанию баллов, применимых к этой оплате (рассчитывается исходя из поля total в GET запросе),
• code - код на оплату для проведения операции.


 

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

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

 

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

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

 

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

 

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", \
"nonce":"uuid", \
"cashier": { \
"externalId":"string", \
"name":"string" \
}, \
"receipt": { \
"total":100.0, \
"cash":50.0, \
"points":50.0, \
"number":"string" \
"skipLoyaltyTotal":10.0 \
"unreedemableTotal":20.0 \
}, \
"tags":[1,2] \
}' -X POST "https://api.uds.app/partner/v2/operations"


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

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

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

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

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

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

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

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

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

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

• tags (список id тегов, которые нужно установить клиенту);


При возвращении ошибки с UDS не проводить оплату в учетной системе до внесения корректировки/устранения ошибки и отправления повторного запроса, т.е. проводить оплату в учетной системе только после получения ответа success. Возможные ошибки описаны ниже

 

Если при оплате/закрытия заказа вернулась ошибка от UDS, то в интерфейсе учетной системы писать соответствующее описание:

 

Статус

Код ошибки

Описание

400

badRequest

Form validation errors occurred. Обратитесь к разработчикам учетной системы

400

invalidChecksum

Удалите в заказе посторонние скидки 

400

insufficientFunds

Попытка списания баллов больше, чем есть у клиента на балансе. Внесите корректировку

400

discountLimitExceed

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

401

unauthorized

Компания не активна или сгенерирован новый API Key Продлите, пожалуйста, подписку UDS.

404

notFound

Неверно введен код клиента или время жизни кода истекло. Введите новый код клиента

404

cashierNotFound

Идентификатор в cashierExternalId недопустим. Принимаются только цифры и латинские буквы без пробелов


Реализовать возможность отмены оплаты, т.е. при отмене в учетной системе также должна происходить отмена транзакции в UDS. Запрос Refund c 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"

 

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

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

 

Важно! Обязательным условием использования данного функционала является настройка модуля программы лояльности в настройках административной панели UDS Business  (https://admin.uds.app/). Вам необходимо указать Начислять бонусные баллы в блоке настройки Способ предоставления  скидки и поставить базовый статус больше 0

mceclip0.png

  • Endpoint

https://api.uds.app/partner/v2/operations​/voucher

Метод - POST

Создание ваучера на проведение операции в 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": 50.0 \
              } \
            }' -X POST "https://api.uds.app/partner/v2/operations/voucher"

В запросе Voucher передаются следующие параметры:
• total (изначальная сумма счета); Если в заказе присутствуют сторонние скидки, тогда сумма total должна указываться после применения этих скидок.
• skipLoyaltyTotal – сумма, на которую не должен начисляться кешбэк. Если в заказе присутствуют товары, которые не должны участвовать в системе UDS (т.е. на эти товары не распространяются скидки), то нужно передать в этом поле их сумму.
• externalId и name - идентификатор и имя кассира, производивший оплату. Externalid может состоять только из цифр и латинских букв. В кассовой системе этим идентификатором может являться id или номер сотрудника;
• number (номер чека в кассовой системе);

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

VoucherInfo{

code

string

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

qrCodeText

string

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

qrCode128

string

Ссылка  для генерирования картинки QR кода (size 128), которую можно распечатать.

qrCode256

string

Ссылка  для генерирования картинки QR кода (size 256), которую можно распечатать.

expiresIn

string($date-time)

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

points

number

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

}

 

Возвращаемые ошибки

Status

Error Code

Description

400

invalidChecksum

Способ предоставления скидки не кешбэк (CHARGE_SCORES)

400

invalidChecksum

Поля total, skipLoyaltyTotal не коррелируют с маркетинговыми настройками компании

400

invalidChecksum

Размер начисляемых бонусных баллов равен 0

400

invalidChecksum

Поле total меньше или равно skipLoyaltyTotal

 

Протестируйте интеграцию согласно чек-листу

Помогла ли вам статья?