API-Bonus BENZUBER (1.0.lk)

API-Bonus Benzuber – протокол для обеспечения взаимодействия между учетной системой партнера (PS) и сервисом "Benzuber Bonus" (BZ).

Протокол позволяет реализовывать сценарии управления и обмен информацией о бонусной системе партнера в сервисе «BENZUBER» для решения бизнес-задач каждого участника.

ВАЖНО

Использование этого API доступно для бонусных систем партнёра расположенных в системе Benzuber. Т.е. пользователи, бонусный баланс и бонусные операции хранятся и обрабатываются в Benzuber.

Функционал API является дополнительной/альтернативной возможностью к "ручной" работе в личном кабинете "Бонусной системы партнёра" по управлению данными.

Доступные запросы:

• Получение информации об обшем доступном балансе бонусной системы /api/v1/balance/get
• Добавление пользователя в бонусную систему /api/v1/clients/add/
• Редактирование пользователя /api/v1/clients/edit/
• Удаление пользователя /api/v1/clients/remove/
• Запрос актуального списка пользователей /api/v1/clients/get/
• Установка полного списка пользователей /api/v1/clients/set/
• Запрос списка операций пользователя по бонусной системе /api/v1/clients/payments/get/
• Операция начисления или списания бонусов для пользователя /api/v1/clients/payments/set/
• Получении информации о топливных заказах пользователей /api/v1/orders/get/

Для обеспечения безопасного доступа и идентификации партнера для работы с протоколом предоставляются логин login и уникальный ключ apikey, которые используется для авторизации и "подписи" каждого запроса.

Базовый URL_BZ – адрес для обращения к серверу BZ. HTTP/HTTPS POST-запрос вида: URL_BZ+/api/v1/команда?id={login}&crc={подпись}

Базовый URL_PS – адрес для обращения к партнеру. Для реализации запросов от Benzuber к партнеру. Все запросы выполняются HTTP/HTTPS POST-запросами вида: URL_PS+/команда?id={login}&crc={подпись}.

Запрос:
   {
       "параметр":"значение",
       ...
   }
Ответ:
   {
       "параметр":"значение",
       ...
   }

HTTP коды ответа на запросы:

200 – запрос выполнен успешно
404 – метод не найден
500 – ошибка выполнения запроса, некорректные параметры запроса

HTTP-код ответа при выполнении запросов означает только состояние получения (доставки) запроса, без учета анализа содержимого запроса. В случае успешного получения запроса сервером (статус 200), в ответе содержится параметр response, который определяет фактическое состояние обработки содержимого полученного запроса.

Возможные варианты response

В случае response!=success, в ответе может быть представлен дополнительный параметр description с текстовым описанием ошибки.

Подпись в запросах (CRC-контрольная сумма)

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

Алгоритм формирования подписи:

1. Взять JSON-строку передаваемого тела запроса ( $string = string(JSON) )
2. Добавить в конец строки Apikey ( $string .= $apikey;)
3. Рассчитывается SHA-1 полученной строки ( sha1( $string ) )
4. Полученное значение используется как параметр "подписи" crc в запросе

Пример:

apikey = "pass425"
тело запроса (json): {"client_id":"abcdefg","timestamp":"123545"}

1) $string = '{"client_id":"abcdefg","timestamp":"123545"}'   //в строку
2) $string ='{"client_id":"abcdefg","timestamp":"123545"}pass425' //+apikey
3) sha1($string) = "d86624155c60bde94321a79ca69f4f2545adfb50"

Запросы от партнера в систему Benzuber:

Получение информации об обшем доступном балансе бонусной системы

Возможность получения актуального значения текущего общего баланса бонусной системы

Запрос

(POST) URL_BZ + /api/v1/balance/get

Request body schema application/json

{
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "balance": (string)
}

Добавление пользователя партнера в Benzuber

Для возможности использования бонусов пользователя в Benzuber, первично необходимо создать пользователя. Первичная идентификация пользователя происходит по сотовому номеру пользователя. Дальнейшие операции с пользователем по полученному идентификатору в системе Benzuber.

Запрос

(POST) URL_BZ + /api/v1/clients/add/

Request body schema application/json

{
    "phone": (string),
    "inn": (string),
    "name": (string),
    "is_enable": (boolean),
    "percent": (string),
    "maximum": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "client_id": (string),
    "description": (stri
}

Редактирование пользователя партнера в Benzuber

Возможность изменения параметров использования бонусов пользователя.

Запрос

(POST) URL_BZ + /api/v1/clients/edit/

Request body schema application/json

{
    "client_id": (string),
    "phone": (string),
    "inn": (string),
    "name": (string),
    "is_enable": (boolean),
    "percent": (string),
    "maximum": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "description": (stri
}

Удаление пользователя партнера в Benzuber

В случае необходимости запрета использования бонусов пользователем, необходимо удалить пользователя партнера из Benzuber

Запрос

(POST) URL_BZ + /api/v1/clients/remove/

Request body schema application/json

{
    "client_id": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string)
}

Запрос актуального списка пользователей партнера в Benzuber

С целью актуализации и синхронизации списка пользователей, которым предоставлено использование бонусов в Benzuber, можно получить текущий полный список добавленных пользователей. Либо запросить информацию по конкретному пользователю.

Запрос

(POST) URL_BZ + /api/v1/clients/get/

Request body schema application/json

{
    "client_id": (String),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "clients": (array)
}

Установка полного списка пользователей партнера в Benzuber

При необходимости можно передать полный список пользователей партнера, которым должно быть доступно использование бонусной системы партнера. Передаваемый список полностью заменяет ранее добавленных пользователей в Benzuber.

Запрос

(POST) URL_BZ + /api/v1/clients/set/

Request body schema application/json

{
    "list": (array),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "description" : (string)
}

Запрос информации о бонусных операциях пользователя

Получение текущего баланса пользователя и списка операций начисления/списания бонусов

Запрос

(POST) URL_BZ + /api/v1/payments/get/

Request body schema application/json

{
    "client_id": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "balance": (double),
    "operations": (array)
}

Операция списания/начисления бонусов для пользователя

Начисление и списание бонусных баллов на балансе пользователя.

Запрос

(POST) URL_BZ + /api/v1/clients/payments/set/

Request body schema application/json

{
    "client_id": (String),
    "amount": (string),
    "description": (string),    
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

{
    "response": (string),
    "description": (string)
}

Получение информации о заказах в системе Benzuber

Получение информации о топливных заказах в Benzuber, в которых была применена бонусная система партнера. Получение выборки, как по отдельным заказам, по конкретному пользователю и за период.

Запрос

(POST) URL_BZ + /api/v1/orders/get/

Request body schema application/json

{
    "order_id": (string),
    "client_id": (string),
    "from": (DateTime),
    "till": (DateTime),
    "timestamp": (DateTime),
}

Ответ

Content type: application/json

{
    "response": (string),
    "orders": (array)
}