API Часто задаваемые вопросы

• Где можно ознакомиться с API UDS?

Документация находится на https://docs.uds.app/ Также есть технические задания по интеграции с кассовыми системами, интернет-магазинами, заказами.

• Какие функции поддерживает API?
  1. Получение информации о компании
  2. Получение списка клиентов компании
  3. Получение информации о клиенте компании
  4. Получение списка проведенных операций
  5. Получение информации о проведенной операции
  6. Получение списка товаров/ категорий
  7. Получение информации о товаре/ категории
  8. Получение информации о заказе
  9. Поиск информации о клиенте по 6-значному коду из приложения UDS App, номеру телефона, UID
  10. Создание операции
  11. Возврат по операции
  12. Расчет максимального количества списываемых бонусов/ размера скидки для операции
  13. Начисление бонусных баллов
  14. Создание товара/ категории
  15. Редактирование товара/ категории
  16.  Удаление товара/ категории
  17. Редактирование заказа
  18. Закрытие заказа
  19. Генерирование кода клиента для заказа
  20. Webhook по новым операциям, заказам, клиентам

• Где можно получить код клиента (QR код) для проведения оплат?

Вы можете установить себе мобильное приложение UDS App (iOS, Android), зарегистрироваться в нем. Для генерации 6-значного кода нажмите на карту в приложении 

• Какая длительность жизни 6-значного кода?

Время жизни кода 45 минут. Досрочно действие кода прерывается при проведении оплаты по нему 

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

Необходимо при запросе customer find добавить параметр exchangeCode=true, тогда в ответе с информацией о клиенте в поле code придет длинный код, по которому можно списывать баллы в течение 24 часов

• Чем отличается процесс оплаты по виртуальной карты 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+)")

• Как можно получить тестовый доступ к API?

Напишите нам на [e-mail] для предоставления тестовой лицензии

• Где можно найти API Key и company ID?

ID компании и API Key можно скопировать в Настройках UDS Бизнес в окне Интеграция.

• Можно ли использовать один API Key и ID компании на  нескольких кассах?

У каждой компании только одни данные для интеграции в UDS, поэтому на всех кассах указываются один API Key и ID компании. Идентификация по кассам/ филиалам/ сотрудникам осуществляется передачей параметров в поле cashier

• Можно ли менять процент начисляемых баллов на покупку клиентов?

Нет, начисление бонусных баллов зависит от параметра cash и от бонусных настроек компании. Для ограничения начисляемых баллов можно передать параметр skipLoyaltyTotal - сумму счета, на которую не должны начисляться бонусные баллы

• Можно ли списывать бонусные баллы по номеру телефона или по UID клиента?

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

• Что такое внешний идентификатор сотрудника?

Для идентификации сотрудника, который проводил оплату на кассе по UDS необходимо отправлять индивидуальный номер сотрудника - его идентификатор. Этот идентификатор можно установить в UDS Бизнес для каждого сотрудника в соответствующем поле - внешнем идентификаторе. 

•  Что означает 400-й ответ?

Статус	Код ошибки	Описание
400	badRequest	Произошла ошибка проверки достоверности формы. Например, это может быть несоответствие типов или ошибки нарушения ограничений. Возникает при передаче некорректного запроса
403	forbidden	Доступ запрещен, данный токен аутентификации не установлен или не имеет соответствующего разрешения. Необходимо проверить актуальность API Key и ID компании и корректность аутентификации Basic
400	invalidChecksum	Итог чека не совпадает с суммой примененных бонусов и деньгами. Должно быть в случае: Начисления бонусных баллов total= cash + points . Например, total =100, cash  = 50,  points = 50 Предоставления скидки total =(cash + point)/(1 - процент скидки). Например, total =100, cash  = 50,  points = 40 (для скидки в 10%) Ошибки часто возникают при применении сторонних скидок, неверном округлении
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 секунд.