Где можно ознакомиться с API UDS?
Документация находится на https://docs.uds.app/ Также есть технические задания по интеграции с кассовыми системами, интернет-магазинами, заказами.
Какие функции поддерживает API?
Где можно получить код клиента (QR код) для проведения оплат?
Вы можете установить себе мобильное приложение UDS App (iOS, Android), зарегистрироваться в нем. Для генерации 6-значного кода нажмите на карту в приложении
Какая длительность жизни 6-значного кода?
Время жизни кода 45 минут. Досрочно действие кода прерывается при проведении оплаты по нему
Как получить код с увеличенным сроком действия?
Необходимо при запросе customer find добавить параметр exchangeCode=true, тогда в ответе с информацией о клиенте в поле code придет длинный код, по которому можно списывать баллы в течение 24 часов. Длинный код генерируется только для кода клиента из приложения, для кода сертификата, заказа, карте wallet в ответе возвращается исходное значение отправляемого кода без увеличения срока действия
Почему в ответе возвращается пустое поле code при поиске клиента?
Поле code приходит при условии, что запрос по поиску клиента осуществляется по коду клиента из приложения UDS App, коду сертификата, коду заказа или карте wallet, а также передается параметр exchangeCode=true
Можно ли получить код клиента по API?
Нет, код клиента возможно получить только через приложение UDS App
Чем отличается процесс оплаты по виртуальной карты Wallet от кода из приложения?
В отличии от кода из приложения у кода виртуальной карты срок действи неограничен, но он действует только в той компании, в которой виртуальная карта получена. В остальном процесс получения информации о клиенте, проведение операции не отличаются.
Как сканировать код виртуальной карты с помощью 2D сканера?
В отличии от кода из приложения в QR коде виртуальной карты содержится ссылка вида
https://wallet.uds.app/add-wallet/{company_id}?ref={код карты}. Необходимо считывать параметер ref и по нему проводить поиск клиента и проведение операции в Partner API.
Примеры обработки
/^(?:https?:\/\/)?(?:www\.)?wallet.+\?(?:.+&)?ref=(\d+)/gm Pattern WALLET_REF_URL_PATTERN = Pattern.compile( "^(?:https?://)?(?:www\\.)?wallet.+\\?(?:.+&)?ref=(\\d+)")
Почему в ответе возвращается пустое поле phone при поиске клиента?
Как можно получить тестовый доступ к API?
Напишите нам на support@uds.app для предоставления тестовой лицензии
Где можно найти API Key и company ID?
ID компании и API Key можно скопировать в Настройках UDS Бизнес в окне Интеграция.
Можно ли использовать один API Key и ID компании на нескольких кассах?
У каждой компании только одни данные для интеграции в UDS, поэтому на всех кассах указываются один API Key и ID компании. Идентификация по кассам/ филиалам/ сотрудникам осуществляется передачей параметров в поле cashier
Можно ли менять процент начисляемых баллов на покупку клиентов?
Нет, начисление бонусных баллов зависит от параметра cash и от бонусных настроек компании. Для ограничения начисляемых баллов можно передать параметр skipLoyaltyTotal - сумму счета, на которую не должны начисляться бонусные баллы
Можно ли списывать бонусные баллы по номеру телефона или по UID клиента?
По номеру телефона бонусы можно списывать при условии, что в компании активна соответствующая настройка (включается на через техническую поддержку). По uid нельзя списывать бонусные баллы, только копить.
Может ли отличаться процент списания баллов у клиентов?
Да, в зависимости от бонусных настроек компании и статуса клиента, процент списания баллов может отличаться.
Как определить максимальную сумму списываемых баллов?
Для упрощения логики расчета максимального процента списания баллов в Partner API v2 при запросе поиска клиента рекомендуем передавать параметр total, равный сумме чека за вычетом сторонних скидок и при необходимости суммы товаров, которая не должна участвовать в расчете списываемых баллов.
Тогда в ответе поиска клиента в объекте purchase -> maxPoints вернется максимально допустимое количество баллов, которое может быть применено к этому чеку (зависит от параметра total). Данное решение еще будет также совместимо в случае возможности списания баллов по номеру телефона- в maxPoints также будет приходить доступные баллы
Также размера допустимых баллов для списания можно получить, отправив отдельный запрос для расчета параметров операции
Что такое внешний идентификатор сотрудника?
Для идентификации сотрудника, который проводил оплату на кассе по UDS необходимо отправлять индивидуальный номер сотрудника - его идентификатор. Этот идентификатор можно установить в UDS Бизнес для каждого сотрудника в соответствующем поле - внешнем идентификаторе.
Что означает 400-й ответ?
Статус |
Код ошибки |
Описание |
400 |
badRequest |
Произошла ошибка проверки достоверности формы. Например, это может быть несоответствие типов или ошибки нарушения ограничений. Возникает при передаче некорректного запроса |
403 |
forbidden |
Доступ запрещен, данный токен аутентификации не установлен или не имеет соответствующего разрешения. Необходимо проверить актуальность API Key и ID компании и корректность аутентификации Basic |
400 |
invalidChecksum |
Итог чека не совпадает с суммой примененных бонусов и деньгами. Должно быть: cash = total - points - (total - skipLoyaltyTotal)*процент скидки
Ошибки часто возникают при применении сторонних скидок, неверном округлении
|
400 |
insufficientFunds |
Попытка списания бонусных баллов больше, чем есть у клиента на балансе. Ошибка в основном возникает при неверном округлении, окгруглять баллы можно только в меньшую сторону |
400 |
discountLimitExceed |
Попытка списания бонусных баллов больше, чем допустимо по маркетингу. Компания может установить максимальный процент от чека, на который допускается списать бонусы. Посмотреть допустимый процент списания баллов можно в UDS Бизнес в Настройки - Бонусная программа в графе Какой процент счета можно оплатить баллами? |
403 |
companyIsInactive |
Компания не активна. Необходимо продлить подписку |
404 |
notFound |
Запрошенный объект, API-метод или путь не существует. В основном, возникает при неверно введенном коде клиента или время жизни кода истекло. Также возникает при запросе find по номеру телефона, если такой номер в системе не зарегистрирован и по нему в компании ранее не было операций. Необходимо ввести новый 6-значный код клиента из приложения UDS App. Проверить верно ли указан API метод, URL и существует ли объект (это может быть ID клиента, товара, операции). В случае запроса post ошибка может возникать, если в headers не передается заголовок Content-Type: application/json |
Какая версия протокола TLS поддерживается?
Минимальная версия TLS от 1.1
Поддерживается ли работа через http протокол?
Нет, запросы должны использовать https протокол
Поддерживается ли метод вебхуков (webhook)?
Да, вебхуки отправляются в случае присоединения к компании нового клиента, проведения операции и при создании заказа
Как настроить вебхук?
Вебхук настраивается в Настройках UDS Бизнес в окне Интеграция. Для уведомлении о событии необходимо указать адрес Вашего сервера, куда будет отправляться вебхука
Почему приходят несколько вебхуков с одинаковой информацией?
Вебхук дублируется, если по каким-то причинам он не был доставлен или не был получен 200-й ответ в течение 5 секунд.
Можно ли получить вебхук по одному событию на несколько адресов?
Нет, отправка вебхука осуществляется тольк она один адрес
Есть ли примеры запросов в Partner API?
Примеры запросов доступны по ссылке
Как ограничить начисление или списание баллов на товары?
Для ограничения начисления баллов необходимо в запросе создания транзакции /operation передать в теле запроса параметр skipLoyaltyTotal - сумму товаров, на которую не должны начисляться баллы.
Если используется устревшая версия Partner API v1, то расчет ограничений по списанию бонусов полностью должен осуществляться на стороне интеграционного модуля. Для ограничения начисления бонусов необходимо вычесть товары из суммы чека на стороне интеграционного модуля и не передавать их в UDS, то есть передать сумму чека только с учетов товаров, на которые могут быть начислены бонусы.
Как понять, что применятся код сертификата, а не код из приложения
При поиске клиента find можно понять, что вводится код сертификата - при запросе поиска клиента по коду в ответе в параметре type возвращается тип введенного кода "PURCHASE", "BONUS_ITEMS_PURCHASE", "GOODS_ORDER_COMPLETE", "CERTIFICATE"
Как узнать сумму начисляемых бонусов за покупку?
Необходимо воспользоваться методом calc и указать такие же параметры, которые будут отправлены при проведении операции. В ответ на запрос расчета calc количество бонусов вернется в объекте purchase-> cashBack.
Так же вы можете расчитать самостоятельно по формуле: количество бонусов = (сумма оплаты деньгами (cash) - сумма товаров, на которые не должны начислиться бонусы (skipLoyaltyTotal))*процент начисления бонусов согласно статусу клиента (cashBackRate). Если значение получается меньше или равно 0, то бонусы за такую покупку не начисляться.
Можно ли получить список заказов в компании?
Нет, на текущий момент получить информацию можно только по идентификатру заказа
Поддерживается ли изменение статуса заказа по API?
Нет, на текущий момент статус заказа можно изменить только в UDS Бизнес
Можно ли отменить заказ по API?
Нет, на текущий отменить заказ можно только в UDS Бизнес