API-B2B BENZUBER AGENT

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

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

API предоставляется для компаний агентов, которые могут регистрировать компании в сервисе "Benzuber для Бизнеса"

Запросы доступные для агентов:

• Авторизация партнера auth
• Передачи информации об юридическом лице – клиенте партнера newclient
• Получение информации об актуальном топливном балансе юридического лица в системе «Benzuber для бизнеса» clientbalance
• Получение информации об актуальном статусе юридического лица в системе «Benzuber для бизнеса» clientstatus
• Получение авторизационной ссылки клиента для входа в личный кабинет «Benzuber для бизнеса» getclientURL
• Передача информации о пополнении топливного баланса клиентом партнера в учетной системе партнера payment
• Уведомление партнера о принятии договора оферты клиентом в личном кабинете «Benzuber для бизнеса» accepted

Для обеспечения безопасного доступа и идентификации партнера для работы с протоколом предоставляется уникальный ключ 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

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

Авторизация

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

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

Инфраструктура 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 для бизнеса» информацию о своём клиенте, который планирует использовать сервис Benzuber.

Запрос

(POST) HOST + /b2b/v1/newclient/

Request body schema application/json

{
 "token": (string),

 "client_id": (string),
 "client_phone": (string),


 "inn": (string),
 "kpp": (string),
 "ogrn": (string),

 "name": (string),
 "full_name": (string),

 "legal_zip": (string),
 "legal_region": (string),
 "legal_city": (string),
 "legal_street": (string),
 "legal_house": (string),
 "legal_build": (string),
 "legal_office": (string),

 "fact_as_legal": (bool),

 "fact_zip": (string),
 "fact_region": (string),
 "fact_city": (string),
 "fact_street": (string),
 "fact_house": (string),
 "fact_build": (string),
 "fact_office": (string),

 "phone": (string),
 "fax": (string),
 "email": (string),

 "account_bik": (string),
 "account_id": (string)
}

Ответ

Content type: application/json

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

Получение информации об актуальном топливном балансе юридического лица в системе «Benzuber для бизнеса»

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

Запрос

(POST) HOST + /b2b/v1/clientbalance/

Request body schema application/json

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

Ответ

Content type: application/json

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

Получение информации об актуальном статусе юридического лица в системе «Benzuber для бизнеса»

Возможность получения актуального статуса клиента в Benzuber.

Запрос

(POST) HOST + /b2b/v1/clientstatus/

Request body schema application/json

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

Ответ

Content type: application/json

{
    "response": (string),
    "active": (bool),
    "accept": (bool)
}

Получение авторизационной ссылки клиента для входа личный кабинет «Benzuber для бизнеса»

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

Запрос

(POST) HOST + /b2b/v1/getclienturl/

Request body schema application/json

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

Ответ

Content type: application/json

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

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

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

Запрос

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

Request body schema application/json

{
    "token": (string),
    "org_id": (string),
    "sum": (double),
    "payment_id": (string)
}

Ответ

Content type: application/json

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

Функции обратного вызова партнеру

С целью оперативного оповещения партнёра о событиях с клиентом в системе “Benzuber для бизнеса» выполняются запросы к партнеру на адрес URL_PS

Принятие клиентом договора оферты «Benzuber для бизнеса”

После принятия клиентом договора оферты в личном кабинете «Benzuber для бизнеса», отправляется уведомление партнеру о принятии.

Запрос

(POST) URL_PS + /accepted

Request body schema application/json

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

Ответ

Content type: application/json

{
    "response": (string)
}