API-Bonus BENZUBER (1.0)

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

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

ВАЖНО

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

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

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

• Добавление пользователя партнера в Benzuber /api/v1/clients/add/

• Удаление пользователя партнера в Benzuber /api/v1/clients/remove/

• Запрос актуального списка пользователей партнера в Benzuber api/v1/clients/get/

• Установка полного списка пользователей партнера в Benzuber /api/v1/clients/set/

• Запрос параметров и баланса пользователя в бонусной системе партнера /balance/

• Операция списания с баланса пользователя в бонусной системе партнера /order/set/

• Операция изменения существующей операции списания с баланса пользователя в бонусной системе партнера /order/change/

• Получении информации о заказах пользователей партнера в Benzuber /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

Подпись в запросах (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:

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

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

Запрос

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

Request body schema application/json

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

Ответ

Content type: application/json

{
    "response": (string)
}

Удаление пользователя партнера в 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

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

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

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

Запрос

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

Request body schema application/json

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

Ответ

Content type: application/json

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

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

Запрос параметров и баланса пользователя в бонусной системе партнера

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

Запрос

(POST) URL_PS + /balance/

Request body schema application/json

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

Ответ

Content type: application/json

{
   "response": (string),
   "balance": (double),
   "percent": (double),
   "maximum": (double),
   "status": (string)
}

Операция списания с баланса пользователя в бонусной системе партнера

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

Запрос

(POST) URL_PS + /order/set/

Request body schema application/json

{
    "client_id": (string),
    "order_id": (string),
    "amount": (string),
    "total": (string),
    "station": (string),
    "address": (string),
    "description": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

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

Операция изменения существующей операции списания с баланса пользователя в бонусной системе партнера

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

Запрос

(POST) URL_PS + /order/change/

Request body schema application/json

{
    "invoice": (string),
    "amount": (string),
    "total": (string),
    "description": (string),
    "timestamp": (DateTime)
}

Ответ

Content type: application/json

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