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

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

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

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

GET /get_balance.php

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

Находит клиента по номеру телефона или по ID. Возвращает текущее количество бонусов на балансе клиента.

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

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

Примеры

GET запрос:

https://{адрес-сервера}/get_balance.php?format=json&client_phone=89991112233

Ответ успех:

{
    "result": "true", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8", // Уникальный идентификатор клиента в бонусной системе
    "phone": "89991112233", // Номер телефона клиента
    "balance": 576 // Текущее количество бонусов на балансе клиента
}

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

{
    "result": "false", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "desc": "Клиент не найден в БД", // Описание ошибки
    "err_num": "FU_13" // Код ошибки
}

Обновить или создать клиента

POST /update_client.php

Доступно с версии 3.5

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

Выполняет поиск клиента в бонусной системе по ID или номеру телефона (если ID не передан). Если клиент есть в системе, то обновляет его данные. Если клиента нет в системе, то создает его. Если в запросе, в client_id будет передан GUID длиной 36 символов, и такого ID еще нет в системе, то новый клиент будет создаваться с переданным client_id. В иных случаях для новых клиентов будет формироваться новый ID.

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

{
    "client_id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8", // Уникальный идентификатор клиента в бонусной системе. Передавать если известен.
    "phone": "89991112233", // Номер телефона клиента. Обязательный параметр.
    "name": "Святослав", // Имя клиента. Обязательный параметр.
    "birthday": "1992-12-31", // Дата рождения клиента в формате ГГГГ-ММ-ДД.
    "email": "mail@mail.ru", // Email клиента
    "group": "512", // ID группы клиента
    "card": ",12391ж" // Номер карты клиента
}

В заголовке X-Jup-Api-Key необходимо передать секретный ключ API (выдается техподдержкой).

Примеры

Ответ успех:

{
    "result": "true", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8", // Уникальный идентификатор клиента в бонусной системе
    "phone": "89991112233", // Номер телефона клиента
    "balance": 576 // Текущее количество бонусов на балансе клиента
}

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

{
    "result": "false", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "desc": "Ключ не авторизован в бонусной системе", // Описание ошибки
    "err_num": "FU_L_154" // Код ошибки
}

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

GET /get_change.php

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

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

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

key - секретный ключ API (выдается техподдержкой). Ключ может передаваться как в параметрах запроса, так и в заголовке X-Jup-Api-Key;
date - дата в формате ГГГГ-ММ-ДД.

Примеры

GET запрос:

https://{адрес-сервера}/get_change.php?date=2021-02-01

Ответ успех:

{
    "0": {
        "client_id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8", // Уникальный идентификатор клиента в бонусной системе
        "balance_total": "576", // Текущее количество бонусов на балансе клиента
        "phone": "89991112233" // Номер телефона клиента
    },
    "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", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "desc": "Ключ не авторизован в бонусной системе", // Описание ошибки
    "err_num": "FU_L_154" // Код ошибки
}

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

GET /get_rank.php

Доступно с версии 3.4

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

Рассчитывает и возвращает текущий ранг клиента. Использовать вместо get_balance если используется ранговая бонусная система.

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

В системе 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%).
Отмены заказа и возвраты на ранг не влияют

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

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

Примеры

GET запрос:

https://{адрес-сервера}/get_rank.php?format=json&client_phone=89991112233

Ответ успех:

{
    "result": "true", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "id": "4092538C-AFB0-3C29-E7FF-F2C0BAB81AC8", // Уникальный идентификатор клиента в бонусной системе
    "phone": "89991112233", // Номер телефона клиента
    "balance": 297, // Текущее количество бонусов на балансе клиента
    "rank": 1, // Текущий ранг клиента
    "start_date": "2022-01-27 18:13:15", // Дата\время начала действия ранга
    "reset_date": "2022-04-27 18:13:15", // Дата\время окончания действия ранга (когда ранг будет сброшен, если не накопить нужную сумму)
    "save_sum": 12000, // Сколько нужно потратить денег (до reset_date ), чтобы сохранить текущий ранг. Если ранг минимальный, то возвращает 0
    "up_sum": 24000, // Сколько нужно потратить денег (до reset_date ), чтобы перейти на следующий ранг. Если ранг максимальный, то возвращает 0
    "saveup_percent": 10, // Сколько % накапливается бонусов с суммы заказа (в соответствии с текущим рангом)
    "pay_percent": 30 // Максимальный % от суммы заказа, который клиент может оплатить бонусами (в соответствии с текущим рангом)
}

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

{
    "result": "false", // Результат обработки запроса. "true" - успех, "false" - ошибка
    "desc": "Клиент не найден в БД", // Описание ошибки
    "err_num": "FU_13" // Код ошибки
}

Система JUPITER www.jupiter.systems (с) 2024г.

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

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

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

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

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

Примеры

Обновить или создать клиента

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

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

Примеры

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

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

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

Примеры

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

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

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

Примеры

Нет комментариев