Перейти к основному контенту

Базовая REST API интеграция

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

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

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

POST /integration/general/client

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

{
    "search":"XXXXXXX", //Телефон, карта или код клиента из приложения
    "point":"62aXXXXX4f4" //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 //Сумма покупки
}

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

{
    "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 минут) — Длительность удержания в минутах (максимум 10 минут).
}

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

{
    "success": true,
    "held": {
          "until":1704045600, //  Время UNIXTIME, до которого баллы будут удержаны.
          "amount":100 //Количество удержанных баллов.
      }
}

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

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

POST: /integration/general/bonuses/release

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

{
    "client":"62aXXXXX2486", //ID клиента
    "point":"62XXXXXf4f4", //ID точки
 }

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

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

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

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

POST: /integration/general/retail

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

{
    "client":"62aXXXXX2486", //ID клиента
    "point":"62XXXXXf4f4", //ID точки
    "amount":100, //Сумма чека
    "spend":100 //Сколько будет списано баллов, если 0 то будет начисление
}

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

{
    "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."
}

Наверх