Метод позволяет напечатать на чеке код ваучера (qr код) и клиент, отсканировав его в приложении UDS App, сможет получить баллы за покупку. Например, клиент забыл телефон, не было времени, сотрудник не рассказал про возможность накопить и т.п., то клиент сможет накопить баллы позже по чеку с таким ваучером. Срок жизни ваучера- 3 часа.
Маркетинговая политика
Важно! Обязательным условием использования данного функционала является настройка модуля программы лояльности в настройках административной панели UDS Business (https://admin.uds.app/). Вам необходимо указать Начислять бонусные баллы в блоке настройки Способ предоставления скидки и поставить базовый статус больше 0
- Endpoint
https://api.uds.app/partner/v2/operations/voucher
Метод - POST
- Заголовки запроса (Headers)
Существует несколько заголовков, которые должны быть размещены в каждом запросе для удовлетворения требований транспортной инфраструктуры.
|
Название |
Формат (тип данных) |
Описание |
|
Accept |
MIME Type |
application/json |
|
Accept-Charset |
String |
utf-8 |
|
Content-Type |
MIME Type |
application/json |
|
X-Origin-Request-Id |
UUID |
идентификатор запроса, используемого приложением; может быть опущен, но его использование рекомендуется |
|
X-Request-Id |
UUID |
идентификатор запроса |
|
X-Timestamp |
ISO 8601 Date |
дата и время создания запроса |
- Аутентификация запросов
Для вызова методов Partner API интегрируемые приложения должны аутентифицировать запросы, используя Basic Auth. Для этого требуется установить значение токена в http-заголовок Authorization. Значение токена - идентификатор вашей компании (company id) и секретный ключ (API Key), закодированные с помощью base64. Создать или получить имеющийся API Key можно на странице Интеграция.
Пример запроса с аутентификацией:
curl -X GET -s https://api.uds.app/partner/v2/settings
-H "Authorization: Basic MTIzNDp0b2tlbg=="
Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах.Где MTIzNDp0b2tlbg== -- это закодированная в Base64 строка 1234:token.
Внимание! Если при отправке запросов возвращается 401 ошибка unauthorized или 403 ошибка forbidden, то API key или id компании введены неверно.
API key (токен) и id компании, которые используются при интеграции с кассой, не должны жестко прописываться в коде. При настройке интеграционного модуля должна быть возможность прописать API key и id в какой-нибудь конфигурационный файл (config), т.к. они для каждой компании свои.
- Числа и округление
Все числа API должны быть округлены с точностью до двух десятичных знаков до ближайшего числа. Все ответы от сервера также должны следовать этому правилу; поэтому каждое поле, рассчитанное на стороне сервера, будет иметь не более двух десятичных цифр, а число будет округлено до ближайшего числа.
Создание ваучера на проведение операции в UDS. В случае успеха вы получите информацию для печати кода и ссылки на графическое отображение QR кода ваучера на чеке.
Возвращаемые ошибки
|
Status |
Error Code |
Description |
|
400 |
invalidChecksum |
Способ предоставления скидки не кешбэк (CHARGE_SCORES) |
|
400 |
invalidChecksum |
Поля total, skipLoyaltyTotal не коррелируют с маркетинговыми настройками компании |
|
400 |
invalidChecksum |
Размер начисляемых бонусных баллов равен 0 |
|
400 |
invalidChecksum |
Поле total меньше или равно skipLoyaltyTotal |
Параметры, которые нужно отправить при создании ваучера
CreateVoucher{
nonce |
stringnullable: trueUUID ваучера, чтобы исключить повторное генерирование ваучера для одного и того же чека |
||||||
cashier |
{
}nullable: trueИдентификатор и имя кассира, производивший оплату. externalId может состоять только из цифр и латинских букв. В кассовой системе этим идентификатором может являться id или номер сотрудника; |
||||||
receipt* |
{
} |
}
*-обязательное поле для заполнения
Ответ на запрос создания ваучера
VoucherInfo{
|
code |
string Числовой код ваучера |
|
qrCodeText |
string Текст для генерации QR - кода ваучера для дальнейшей печати |
|
qrCode64 |
string Ссылка для генерирования картинки QR кода(size 64), которую можно распечатать. |
|
qrCode128 |
string Ссылка для генерирования картинки QR кода (size 128), которую можно распечатать. |
|
qrCode256 |
string Ссылка для генерирования картинки QR кода (size 256), которую можно распечатать. |
|
expiresIn |
string($date-time) Время, когда ваучер сгорит по UTC |
|
points |
number Количество баллов для начисления. Рассчитывается из настроек базового уровня бонусной программы. Если клиент с повышенным статусом отсканирует чек, то бонусы будут начислены согласно статусу клиента |
}
Примечание:
В ответе есть два типа ссылок:
qrCode256(128 или 64) - https://qr.uds.app/qrcode?text=uds://voucher/?code=12345678&s=256 по данной ссылке нужно сделать GET запрос и в ответ получить картинку QR кода для печати.
qrCodeText - https://d.uds.app?link=https%3A%2F%2Fslug.uds.app%2Fc%2Fvoucher%3Fcode%3D75852816&ius=uds&ibi=com.setinbox.TheGame&ofl=https%3A%2F%2Fuds.app&isi=954809132&apn=com.setinbox.game из данной ссылки необходимо самостоятельно сгенерировать Qr код.
В самом QR коде должна быть ссылка только вида
При сканировании подобной ссылки клиент будет перенаправлен в приложение для применения ваучера. Если клиент не скачал приложение, то он будет направлен в магазин приложений и после регстрации автоматически будет предложено использовать ваучер для получения бонусов.
Примеры кода для создания ваучера
- curl
source: |
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"
- PHP
source: >
$date = new DateTime();
$url = 'https://api.uds.app/partner/v2/operations/voucher';
$uuid_v4 = 'UUID'; //generate universally unique identifier version
4 (RFC 4122)
$companyId = 123; //set ID of your company
$apikey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
company apikey
// Set request body
$postData = json_encode(
array(
'nonce' => 'string-UUID',
'cashier' => array(
'externalId' => 'string',
'name' => 'string'
),
'receipt' => array(
'total' => 100.0,
'number' => 'string',
'skipLoyaltyTotal' => 50.0
)
)
);
// Create a stream
$opts = array(
'http' => array(
'method' => 'POST',
'header' => "Accept: application/json\r\n" .
"Accept-Charset: utf-8\r\n" .
"Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
"X-Origin-Request-Id: ".$uuid_v4."\r\n" .
"X-Timestamp: ".$date->format(DateTime::ATOM),
'content' => $postData,
'ignore_errors' => true
)
);
$context = stream_context_create($opts);
$result = file_get_contents($url, false, $context);
echo $result;
- Python
source: |
import json
import uuid
import base64
from datetime import datetime
from http.client import HTTPSConnection
authString = base64.b64encode(b'<companyId>:<apiKey>')
con = HTTPSConnection('api.uds.app')
con.request(
method='POST',
url='/partner/v2/operations/voucher',
body=json.dumps({
'nonce': 'string-UUID',
'cashier': {
'extrnalId': 'string',
'name': 'string'
},
'receipt': {
'total': 100.0,
'number': 'string',
'skipLoyaltyTotal': 50.0
}
}),
headers={
'Accept': 'application/json',
'Accept-Charset': 'utf-8',
'Authorization': 'Basic ' + authString.decode("utf-8") ,
'X-Origin-Request-Id': str(uuid.uuid4()),
'X-Timestamp': datetime.now().isoformat(),
})
print (con.getresponse().read())
con.close()
- Node
source: |
var https = require('https');
var uuid = require('uuid4');
var authString = '<companyId>' + ':' + '<apiKey>';
var options = {
'host': 'api.uds.app',
'port': 443,
'path': '/partner/v2/operations/voucher',
'method': 'POST',
'headers': {
'Accept': 'application/json',
'Accept-Charset': 'utf-8',
'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
'X-Origin-Request-Id': uuid(),
'X-Timestamp': new Date().toISOString()
}
};
var data = JSON.stringify({
'nonce': 'string-UUID',
'cashier': {
'extrnalId': 'string',
'name': 'string'
},
'receipt': {
'total': 100.0,
'number': 'string',
'skipLoyaltyTotal': 50.0
}
});
var req = https.request(options, function(res) {
res.setEncoding('utf8');
res.on('data', function (response) {
console.log(
JSON.parse(response)
);
});
});
req.write(data);
req.end();
Пример ответа
responses: '200'
content: application/json:
{
"qrCode256": "https://qr.uds.app/qrcode?text=https://d.uds.app?link=https%3A%2F%2Fslug.uds.app%2Fc%2Fvoucher%3Fcode%3D12345678&ius=uds&ibi=com.setinbox.TheGame&ofl=https%3A%2F%2Fuds.app&isi=954809132&apn=com.setinbox.game &s=256",
"qrCode128": "https://qr.uds.app/qrcode?text=https://d.uds.app?link=https%3A%2F%2Fslug.uds.app%2Fc%2Fvoucher%3Fcode%3D12345678&ius=uds&ibi=com.setinbox.TheGame&ofl=https%3A%2F%2Fuds.app&isi=954809132&apn=com.setinbox.game &s=128",
"qrCodeText": "https://d.uds.app?link=https%3A%2F%2Fslug.uds.app%2Fc%2Fvoucher%3Fcode%3D12345678&ius=uds&ibi=com.setinbox.TheGame&ofl=https%3A%2F%2Fuds.app&isi=954809132&apn=com.setinbox.game ",
"points": 10.90,
"code": "12345678",
"qrCode64": "https://qr.uds.app/qrcode?text=https://d.uds.app?link=https%3A%2F%2Fslug.uds.app%2Fc%2Fvoucher%3Fcode%3D12345678&ius=uds&ibi=com.setinbox.TheGame&ofl=https%3A%2F%2Fuds.app&isi=954809132&apn=com.setinbox.game &s=64",
"expiresIn": "2021-05-11T18:58:32.361Z"
}