REST API

Базовая REST API интеграция
Для простой интеграции можно использовать базовый REST API, для правильной работы их следует вызывать в том порядке, что представлены в документации. 

 Все методы ожидают ключ apikey в заголовках запроса, получить apikey можно по запросу. 

 1. Поиск клиента в системе лояльности  

 POST /integration/general/client 

 Параметры запроса: 

 {

 "search":"XXXXXXX", //Телефон, карта или код клиента из приложения

 "point":"62aXXXXX4f4", //ID точки

 //Опционально

 "hold":["63aXXXXX4f4"] //ID удержания бонусов, указанные ID будут учтены при расчете текущего баланса

} 

 Успешный ответ на запрос: 

 {

 "success": true,

 "client": {

 "id": "62aXXXXXXX6", //ID клиента, используется в запросах далее

 "name": "ИВАН", //Имя клиента

 "photo": "https://..../XXXXX.jpeg", //Фото клиента

 "birthday": "2021-03-29", //Дата рождения

 "level": {

 "id": "621XXXXXf23", //ID уровня

 "title": "Бонусы", //Название уровня

 "percent": 10, //Процент уровня

 "type": "cashback",//Тип уровня cashback или discount

 "maxSpendPercent": 100 //Максимальный процент списания от чека (если cashback)

 },

 "phone": 7920XXXXXXX, //Номер телефона клиента

 "email": "mail@mail.mail", //Email клиента

 "balance": 878 //Текущий баланс клиента для discount всегда 0

 }

} 

 2. Предварительный расчет операции 

 POST : /integration/general/recalc 

 Параметры запроса: 

 {

 "client":"62aXXXXX486", //ID клиента

 "point":"62aXXXXXXf4", //ID точки

 "amount":100 //Сумма покупки

 //Опционально

 "hold":["63aXXXXX4f4"] //ID удержания бонусов, указанные ID будут учтены при расчете текущего баланса

} 

 Успешный ответ на запрос: 

 {

 "success": true,

 "recalc": {

 "amount": 100, //Сумма покупки

 "percent": 10, //Процент по операции (может отличаться от процента уровня в зависимости от настроек)

 "type": "cashback", //Тип лояльности "cashback" или "discount"

 "spend": 100, //Сколько может списать клиент в этой операции

 "earn": 10 //Сколько будет начислено если операция будет без списания 

 }

} 

 2.5 Удержание бонусных баллов (опционально) 

 Этот метод позволяет временно удержать бонусные баллы пользователя на балансе для предотвращения мошенничества или при длительной операции. Удержание действует в течение 10 минут и может быть автоматически снято (через 10 минут), вручную через метод снятия удержания, либо при создании новой операции на данной точке продаж (ID точки). 

 Удержать бонусы 

 POST: /integration/general/bonuses/hold 

 Параметры запроса: 

 {

 "client":"62aXXXXX2486", //ID клиента

 "point":"62XXXXXf4f4", //ID точки

 "amount":100, //Количество бонусных баллов, которые необходимо удержать

 "duration": 10 // (необязательный, по умолчанию 10 минут) — Длительность удержания в минутах (максимум 30 минут).

} 

 Успешный ответ на запрос: 

 {

 "success": true,

 "held": {

 "id":"6744684....8d193", //ID удержания

 "until":1704045600, // Время UNIXTIME, до которого баллы будут удержаны.

 "amount":100 //Количество удержанных баллов.

 }

} 

 Снять удержание бонусов 

 POST: /integration/general/bonuses/release 

 Параметры запроса: 

 {

 "id":"62aXXXXX2486", //ID удержания

 } 

 Успешный ответ на запрос: 

 {

 "success": true //Статус операции (успешно или ошибка).

} 

 Даже если удержание бонусов не было создано ранее, метод вернет успех на запрос. 

 3. Создание операции 

 POST : /integration/general/retail 

 Параметры запроса: 

 {

 "client":"62aXXXXX2486", //ID клиента

 "point":"62XXXXXf4f4", //ID точки

 "amount":100, //Сумма чека

 "spend":100, //Сколько будет списано баллов, если 0 то будет начисление

 

 //Опционально

 "hold":["63aXXXXX4f4"] //ID удержания бонусов, указанные ID будут учтены при расчете текущего баланса

} 

 Успешный ответ на запрос списания: 

 {

 "success": true,

 "retail": {

 "amount": 100, //Сумма чека

 "total": 0, //Факт оплаты картой или наличными 

 "percent": 10, //Процент 

 "type": "cashback",//Тип лояльности

 "spend": 100 //Сколько было списано баллов

 }

} 

 Успешный ответ на запрос без списания: 

 {

 "success": true,

 "retail": {

 "amount": 100, //Сумма чека

 "total": 100, //Оплата картой или наличными

 "percent": 10, //Процент

 "type": "cashback",

 "earn": 10 //Сколько было начислено

 }

} 

 Примеры ошибок 

 Все ошибки приходят со статусом 422, в теле ответа будет описание ошибки 

 Списание больше допустимого кол-ва: 

 {

 "spend": "Spend can't be more 100"

} 

 Клиент не найден: 

 {

 "client": "Client not found."

} 

 Точка не найдена: 

 {

 "point": "Point not found."

}