API-B2B BENZUBER

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

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

API предоставляется фактическим организациям, использующих сервис "Benzuber для Бизнеса".

Запросы доступные для организаций:

• Авторизация организации auth
  
  
• Получение справочной информации о параметрах топливных лимитах clients/limit/reference
• Получение информации о сотрудниках организации clients/get
• Добавление нового сотрудника организации clients/add
• Редактирование информации о сотруднике clients/edit
• Изменение персонального баланса сотрудника clients/payment
• Установка топливных лимитов сотрудника clients/limit
  
  
• Получение информации о подразделениях организации units/get
• Добавление нового подразделения организации units/add
• Редактирование подразделения организации units/edit
• Изменение персонального баланса подразделения units/payment
• Установка топливных лимитов подразделения units/limit
  
  
• Получение информации об автомобилях организации cars/get
  
  
• Получение информации о балансе организации finance/get
• Получение информации о транзакциях организации transactions/get
  
  
• Получение информации об администраторах организации admins/get
• Установка администратора ответственным за подразделение admins/units

Топливный заказ для сотрудника организации:

Возможность для сотрудников организации самостоятельно создавать топливные заказы используя Web-интерфейс.

• Получение списка сотрудников, которым доступно создание топливного заказа order/clients/get
• Формирование "сессии" для оформления топливного заказа сотрудником order/session/create
• Callback-уведомление о выполненном заказе transaction/notify

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

Базовый URL_BZ – адрес для обращения к серверу BZ. HTTP/HTTPS POST-запрос вида: URL_BZ+/b2b/v1/команда В ответе партнер получает token и URL-адрес (HOST) для обращения по всем прочим запросам.

HOST – адрес для обращения к серверу BZ, полученный после успешной авторизации. Все дальнейшие запросы выполняются HTTP/HTTPS POST-запросами вида: HOST+/b2b/v1/команда

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

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

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

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

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

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

Авторизация

Для начала работы партнер должен пройти первичную авторизацию. Запрос необходимо выполнить по «Базовому URL». При успешной авторизации партнер получает токен (token) и его срок действия. Токен должен использоваться во всех последующих запросах для подтверждения источника запроса.

Срок действия токена назначается случайный образом в диапазоне от 1 до 2 часов.

Инфраструктура Benzuber имеет распределённую архитектуру, поэтому в целях безопасности и оптимизации дальнейшего обмена в успешном ответе содержится адрес хоста host, на который партнер должен отправлять все прочие запросы

Запрос

(POST) Базовый URL_BZ + /b2b/v1/auth/

Request body schema application/json

{
    "apikey": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "token": (string),
    "expiration": (int),
    "host": (string)
}

Параметры топливных лимитов сотрудников

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

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

Запрос

(POST) HOST + /b2b/v1/clients/limit/reference/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "types": (array),
    "modes": (array)
}

Получение списка сотрудников

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

Запрос

(POST) HOST + /b2b/v1/clients/get/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

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

Добавление сотрудника

Возможность добавить нового сотрудника организации

Запрос

(POST) HOST + /b2b/v1/clients/add/

Request body schema application/json

{
    "token": (string),
    "phone": (string),
    "name": (string),
    "car": (string),
    "unit": (string),
    "is_enable": (boolean),
    "is_balance": (boolean),
    "is_odometer": (boolean)    
}

Ответ

Content type: application/json

{
    "response": (string),
    "client_id": (string),
    "description": (string),
    "timestamp": (int)
}

Редактирование сотрудника

Возможность изменения параметров сотрудника организации

Запрос

(POST) HOST + /b2b/v1/clients/edit/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "phone": (string),
    "name": (string),
    "car": (string),
    "unit": (string),
    "is_enable": (boolean),
    "is_balance": (boolean),
    "is_odometer": (boolean)    
}

Ответ

Content type: application/json

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

Изменение персонального баланса сотрудника

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

Запрос

(POST) HOST + /b2b/v1/clients/payment/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "amount": (string)   
}

Ответ

Content type: application/json

{
    "response": (string),
    "balance": (string),
    "description": (string),
    "timestamp": (int)
}

Установка персонального лимита на топливо для сотрудника

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

Запрос

(POST) HOST + /b2b/v1/clients/limit/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "limits": (array)
}

Ответ

Content type: application/json

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

Информация о подразделениях организации

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

Запрос

(POST) HOST + b2b/v1/units/get/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "units": (array),
    "timestamp": (int)
}

Добавление подразделения

Возможность добавить новое подразделение организации

Запрос

(POST) HOST + /b2b/v1/units/add/

Request body schema application/json

{
    "token": (string),
    "name": (string),
    "is_enable": (boolean),
    "is_balance": (boolean)
}

Ответ

Content type: application/json

{
    "response": (string),
    "unit_id": (string),
    "description": (string),
    "timestamp": (int)
}

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

Возможность изменения параметров подразделения организации

Запрос

(POST) HOST + /b2b/v1/units/edit/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "name": (string),
    "is_enable": (boolean),
    "is_balance": (boolean)
}

Ответ

Content type: application/json

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

Изменение персонального баланса подразделения

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

Запрос

(POST) HOST + /b2b/v1/units/payment/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "amount": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "balance": (string),
    "description": (string),
    "timestamp": (int)
}

Установка персонального лимита на топливо для подразделения

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

Запрос

(POST) HOST + /b2b/v1/units/limit/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "limits": (array)
}

Ответ

Content type: application/json

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

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

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

Запрос

(POST) HOST + /b2b/v1/cars/get/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

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

Информация о балансе организации

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

Запрос

(POST) HOST + /b2b/v1/finance/get/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

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

Получение списка транзакций

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

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

Запрос

(POST) HOST + /b2b/v1/transactions/get/

Request body schema application/json

{
    "token": (string),
    "date_start": (string),
    "date_end": (string),
    "client_id": (string),
    "phone": (string),
    "unit_id": (string)
}

или

{
    "token": (string),
    "request_id": (string),
    "offset": (string),
    "limit": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "transactions": (array),
    "request": (array)
}

Получение списка администраторов

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

Запрос

(POST) HOST + /b2b/v1/admins/get/

Request body schema application/json

{
    "token": (string)
}

Ответ

Content type: application/json

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

Установка ответственного за подразделение

Возможность установки администратора организации ответственным за подразделение.

Запрос

(POST) HOST + /b2b/v1/admins/units/

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "units": (string)    
}

Ответ

Content type: application/json

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

Список сотрудников, которым доступно создание топливного заказа

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

Запрос

(POST) HOST + /b2b/v1/order/clients/get

Request body schema application/json

{
    "token": (string),
    "org_id": (string),
    "unit_id": (string)    
}

Ответ

Content type: application/json

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

Формирование "сессии" для оформления топливного заказа

Возможность формирование "сессии" для оформления топливного заказа сотрудником, полуение уникального URL, для использования в WEB-интерфейсе.

Запрос

(POST) HOST + /b2b/v1/order/session/create

Request body schema application/json

{
    "token": (string),
    "id": (string),
    "latitude": (string),
    "longitude": (string)
}

Ответ

Content type: application/json

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

Callback-запрос получение токена партнёра

Для безопасной работы обратных запросов (callback), Benzuber периодически, при необходимости запрашивает актуальный token. В случае ошибки получения токена от партнёра, дальнейшие callback-запросы не отправляются.

CALLBACK_URL - устанавливается в Личном кабинете организации.

Запрос

(POST) CALLBACK_URL + /auth

Request body schema application/json

{
    "apikey": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "token": (string),
    "expiration": (int),
    "host": (string)
}

Callback-уведомление о выполненном заказе

Уведомление партнёра о факте завершения заказа. Запрос отправляется однократно, ответ партнёра на запрос не влияет на обработку.
При необходимости, перед отправкой запрос актуализируется токен партнера.

Запрос

(POST) CALLBACK_URL + /transaction/notify

Request body schema application/json

{
    "token": (string),
    "transaction": (array)
}

Ответ

Content type: application/json

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