Облачная бонусная система. API

Общие сведения

Для работы с бонусной системы необходимо получить в техподдержке адрес сервера и ключ API

Получить текущий баланс клиента

GET /get_balance.php

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

• format - всегда "json"
• key - секретный ключ API (выдается техподдержкой)
• client_phone - номер телефона клиента в формате 89060938273 (только цифры, 11 символов, начинается с 8). Если передан client_id, то телефон можно не передавать.
• client_id - уникальный идентификатор клиента в бонусной системе. Обязательно передавать, если известен.

Параметры ответа

• result - результат обработки запроса
• id - уникальный идентификатор клиента в бонусной системе
• phone - основной номер телефона клиента
• balance - текущее кол-во бонусов на балансе клиента
• desc - описание ошибки (в случае ошибки)
• err_num - код ошибки (в случае ошибки)

Логика работы

• Находит клиента по номеру телефона или по GUID. Возвращает его текущее кол-во бонусов.

Примеры

GET запрос:

https://{адрес-сервера}/get_balance.php?format=json&key={ключ-api}&client_phone=89060938273&client_id=4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8

Ответ успех:

{
   "result": "true",
   "id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8",
   "phone": "89060938273",
   "balance": 576
}

Ответ ошибка:

{
   "result": "false",
   "desc": "Клиент не найден в БД",
   "err_num": "FU_13"
}

Получить список клиентов, у которых изменился баланс баланс

GET /get_change.php

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

• key - секретный ключ API (выдается техподдержкой)
• date - дата в формате ГГГГ-ММ-ДД

Параметры ответа

• client_id - уникальный идентификатор клиента в бонусной системе
• phone - основной номер телефона клиента
• balance_total- текущее кол-во бонусов на балансе клиента
• desc - описание ошибки (в случае ошибки)
• err_num - код ошибки (в случае ошибки)

Логика работы

• Находит и возвращает всех клиентов, у которых изменилось кол-во бонусов (баланс) после указанной даты.

Примеры

GET запрос:

https://{адрес-сервера}/get_change.php?key={ключ-api}&date=2021-02-01

Ответ успех:

{
   "0": {
      "client_id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8",
      "balance_total": "576",
      "phone": "89060938273"
   },
   "1": {
      "client_id": "6D63C237-DFFE-B5BA-6080-86B5FA84A84C",
      "balance_total": "0",
      "phone": "84952231996"
   },
   "2": {
      "client_id": "B8B5BCC6-69AF-1321-ECD4-87ACA8D05D4B",
      "balance_total": "0",
      "phone": "89646441996"
   },
   "3": {
      "client_id": "CA9E5EDF-658D-80CC-BD37-6379A624C13F",
      "balance_total": "0",
      "phone": "89020938273"
   }
}

Ответ ошибка:

{
   "result": "false",
   "desc": "Ключ не авторизован в бонусной системе",
   "err_num": "FU_L_154"
}

Получить текущий ранг клиента

GET /get_rank.php

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

• format - всегда "json"
• key - секретный ключ API (выдается техподдержкой)
• client_phone - номер телефона клиента в формате 89060938273 (только цифры, 11 символов, начинается с 8). Если передан client_id, то телефон можно не передавать.
• client_id - уникальный идентификатор клиента в бонусной системе. Обязательно передавать, если известен.

Параметры ответа

• result - результат обработки запроса
• id - уникальный идентификатор клиента в бонусной системе
• phone - основной номер телефона клиента
• balance - текущее кол-во бонусов на балансе клиента
• rank - текущий ранг клиента
• start_date - дата\время начала действия ранга
• reset_date - дата\время окончания действия ранга (когда ранг будет сброшен, если не накопить нужную сумму)
• save_sum - сколько нужно потратить денег (до reset_date ), чтобы сохранить текущий ранг. Если ранг минимальный, то возвращает 0
• up_sum - сколько нужно потратить денег (до reset_date ), чтобы перейти на следующий ранг. Если ранг максимальный, то возвращает 0
• saveup_percent - сколько % накапливается бонусов с суммы заказа (в соответствии с текущим рангом)
• pay_percent - максимальный % от суммы заказа, который клиент может оплатить бонусами (в соответствии с текущим рангом)
• desc - описание ошибки (в случае ошибки)
• err_num - код ошибки (в случае ошибки)

Логика работы

Общее описание ранговой системы:

• В системе 4 ранга, на каждом ранге клиент накапливает разный % бонусов с заказа.
  • 0 ранг - 5%
  • 1 ранг - 10%
  • 2 ранг - 15%
  • 3 ранг - 20%
• От ранга зависит % от суммы заказа, который клиент может оплатить бонусам.
  • 0 ранг - 20%
  • 1 ранг - 30%
  • 2 ранг - 40%
  • 3 ранг - 50%
• Ранги имеют ограниченное время действия. Отсчёт действия ранга начинается с момента перехода на ранг (при повышении или понижении).
  • 0 ранг - бессрочно
  • 1 ранг - 90 дней
  • 2 ранг - 120 дней
  • 3 ранг - 180 дней
• Если по истечении периода действия ранга, клиент не совершит покупки на нужную сумму, то ранг будет понижен на 1.
  • 0 ранг - не понижается
  • 1 ранг - 12 000 руб.
  • 2 ранг - 24 000 руб.
  • 3 ранг - 50 000 руб.
• Если в течении периода действия ранга, клиент совершит покупки на нужную сумму, то ранг будет повышен на 1.
  • 0 ранг - от 12 000 руб.
  • 1 ранг - от 24 000 руб.
  • 2 ранг - от 50 0000 руб.
  • 3 ранг - не повышается
• При повышении ранга, клиент может "перепрыгнуть" ранг при разовой большой покупке.
  • Пример:
    • Текущий ранг 0 (условие повышения 12 000).
    • Клиент сделал заказ на 26 000 руб.,
    • Клиенту будет присвоен сразу 2ой ранг, т.к. эта сумма покрывает сразу два условия перехода: с 0 на 1 ранг, и с 1 на 2 ранг 
• При переходе на ранг (повышении или понижении) сумма покупок обнуляется.
  • Пример:
    • Текущий ранг 1 (условие повышения 24 000 руб.)
    • 01-01-2022 11:10 клиент сделал заказ на 37 000 руб.
    • Ранг повышается на 1. Становится 2
    • Чтобы перейти на 3 ранг, клиент должен сделать покупки на 50 000 руб. до 30-06-2022 11:10
    • Чтобы удержать 2 ранг, клиент должен сделать покупки на 24 000 руб. до 30-06-2022 11:10
    • Т.е. сумма сверх необходимого (13 000 руб.) не учитывается в прогрессе следующих рангов
  • Пример №2:
    • Текущий ранг 1 (условие удержания 12 000 руб.)
    • Ранг действует до 30-06-2022 11:00
    • На момент окончания действия ранга, клиент потратил 13 000 руб.
    • 30-06-2022 11:00 ранг будет пересчитывается
    • Т.к. клиент потратил нужную сумму для сохранения ранга, но недостаточную для повышения, у клиента сохраняется 1ый ранг
    • После пересчета ранга, чтобы снова удержать 1ый ранг, клиент должен сделать покупки на 12 000 руб.
    • Т.е. сумма сверх необходимого (1 000 руб.) не учитывается в прогрессе следующих рангов
• Смена ранга происходит после накопления бонусов.
  • Пример:
    • Текущий ранг 0 (накопление 5%).
    • Клиент сделал заказ на 100 000 руб. 
    • С заказа будет начислено 5 000 руб.  (5%).
• Отмены заказа и возвраты на ранг не влияют

Примеры

GET запрос:

https://{адрес-сервера}/get_rank.php?format=json&key={ключ-api}&client_phone=89060938273&client_id=4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8

Ответ успех:

{
 "result": "true",
 "id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8",
 "phone": "89060938273",
 "balance": 297,
 "rank": 1,
 "start_date": "2022-01-27 18:13:15",
 "reset_date": "2022-04-27 18:13:15",
 "save_sum": 12000,
 "up_sum": 24000,
 "saveup_percent": 10,
 "pay_percent": 30
}

Ответ ошибка:

{
   "result": "false",
   "desc": "Клиент не найден в БД",
   "err_num": "FU_13"
}