WebView Benzuber

WebView Benzuber – это набор визуальных web-компонент и api-запросов, для возможности использования сервиса заправки Benzuber во внешнем приложении..

Web-компоненты - это набор web-страниц, позволяющий отобразить карту с АЗС, выбрать нужную станцию, оформить заказ и отслеживать ход выполнения заказа.

API-запросы - это набор запросов для инициирования сессии пользователя и обмена информацией о ходе выполнения заказа между Benzuber и партнёром.

Общий сценарий работы

• Пользователь приложения партнёра хочет воспользоваться сервисом "заправка"
• Партнёр инициирует "сессию" и отображает пользователю webView с заправками
• Пользователь выбирает АЗС и оформляет заказ
• Benzuber получает заказ и ожидает подтверждения оплаты от партнёра
• Benzuber исполняет заказ на АЗС, отображая ход обработки для пользователя
• Benzuber уведомляет партнёра о завершении заказа

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

• Создание "сессии" /order/init/
• Состояния заказа /order/"сессия"/
• Подтверждение оплаты заказа /order/"сессия"/accept/

Callback-запросы доступные для партнёра:

• Уведомление о создании заказа /order
• Уведомлении об успешном завершении заказа /complete
• Уведомление об отмене заказа /cancel
• Уведомление о формировании фискального чека /receipt

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

Базовый URL_BZ – адрес для обращения к серверу Benzuber. Все дальнейшие запросы выполняются HTTPS GET-запросами вида: URL_BZ+/команда.

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

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

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

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

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

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

Создание "сессии"

Создание "сессии" обеспечивает дальнейшее взаимодействие по заказу. При успешной обработке запроса партнёр получает уникальный URL адрес для запуска и отображения в WebView своего приложения.

Запрос

(GET) URL_BZ + /order/init/?apikey={string}&
    callback={string}&phone={string}&email={string}&
    lon={numeric}&lat={numeric}&
    maximum={numeric}&fuel={string}

Ответ

Content type: application/json

{
    "success": (boolean),
    "session": (string),
    "url": (string),
    "description": (string)
}

Пример

Пример запроса
URL_BZ/order/init/?apikey=123&callback=http%3A%2F%2Fexample.com
            &phone=79222222222&lon=16.123456&lat=23.543210

пример успешного ответа:
{"success":true,"session":"abcdefg","url":"https://benzuber.ru/abcdefg/map/"}

пример неуспешного ответа:
{"success":false,"description":"Invalid authentication"}

Состояния заказа

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

Запрос

(GET) URL_BZ + /order/"идентификатор сессии"/?apikey={string}

Ответ

Content type: application/json

{
    "success": (boolean),
    "is_final": (boolean),
    "status": (string),
    "brand": (string),
    "station": (string),
    "region": (string),
    "city": (string),
    "address": (string),
    "pump": (numeric),
    "fuel": (string),
    "price": (numeric),
    "order_volume": (numeric),
    "order_amount": (numeric),
    "order_bill": (numeric),
    "fact_volume": (numeric),
    "fact_amount": (numeric),
    "fact_bill": (numeric),
    "description": (string)
}

Пример

Пример запроса
URL_BZ/order/abcdefg/?apikey=123

примеры успешного ответа:
{ "success":true, "is_final":false, "status":"created",
  "brand":"Benzuber","station":"Benz-02",
  "region":"Свердловская область","city":"Екатеринбург","address":"Космонатов 10",
  "pump":"2","fuel":"АИ-92","price":"43.52",
  "order_volume":"2.3","order_amount":"100.07","order_bill":"97.77"
}

{ "success":true,"is_final":true,"status":"completed",
  "brand":"Benzuber","station":"Benz-02",
  "region":"Свердловская область","city":"Екатеринбург","address":"Космонатов 10",
  "pump":"2","fuel":"АИ-92","price":"43.52",
  "order_volume":"2.3","order_amount":"100.07","order_bill":"97.77"
  "fact_volume":"1.8","fact_amount":"78.34","fact_bill":"76.54"
}

пример неуспешного ответа:
{"success":false,"description":"Invalid authentication"}

Подтверждение оплаты

Отправка партнёром подтверждения об оплате (холдировании) средств клиента по созданному заказу. Фактическая передача и исполнение заказа со стороны Benzuber происходит только после получения этого уведомления от партнёра.

Запрос

(GET) URL_BZ + /order/"сессия"/accept/?apikey={string}

Ответ

Content type: application/json

{
   "success": (boolean),
   "description": (string)
}

Пример

Пример запроса
URL_BZ/order/abcdefg/accept/?apikey=123

пример успешного ответа:
{"success":true}

пример неуспешного ответа:
{"success":false,"description":"Invalid order state"}

Callback-запросы доступные для партнёра:

Для возможности оперативного получения информации от Benzuber о ходе выполнения заказа, реализован механизм обратного вызова, т.е. когда Benzuber отправляет запросы партнёру. Отправка таких запросов возможна только в случае если при создании "сессии" /order/init/ был указан параметр callback. Иначе, партнёр должен сам запрашивать состояния заказа для отслеживания статуса /order/"сессия"/

Уведомление о создании заказа

После того как пользователь в WebView выбрал АЗС и оформил заказ, этот заказ фиксируется в Benzuber и переходит в состояние ожидания оплаты. Партнёру отправляется уведомление о созданном заказе.

(POST) URL_PS + /order?apikey={string}

Request body schema application/json

{
   "id": "string",
   "brand": "string",
   "station": "string",
   "region": "string",
   "city": "string",
   "address": "string",
   "pump": "numeric string",
   "fuel": "string",
   "price": "numeric",
   "order_volume": "numeric string",
   "order_amount": "numeric string",
   "order_bill": "numeric string"
}

Ответ
Анализируется HTTP-код ответа на запрос. В случае получения любого кода ответ отличного от 200, либо в случае таймаута запроса, заказ автоматически переводится в финальное состояния со статусом notpayed

Пример

Пример запроса
Callback URL_PS +URL_BZ/order?apikey=123
{ "id":"abcdefg", "brand":"Benzuber","station":"Benz-02",
  "region":"Свердловская область","city":"Екатеринбург","address":"Космонавтов 10",
  "pump":"2","fuel":"АИ-92","price":"43.52",
  "order_volume":"2.3","order_amount":"100.07","order_bill":"97.77"}

пример успешного ответа:
HTTP / 200 OK

пример неуспешного ответа:
HTTP / 400 ERROR

Уведомлении об успешном завершении заказа

После фактического завершения налива на АЗС партнёру отправляется уведомление с данными фактически отпущенного топлива.

Запрос

(POST) URL_PS + /complete?apikey={string}

Request body schema application/json

{
    "id": "string",
    "fact_volume": "numeric string",
    "fact_amount": "numeric string",
    "fact_bill": "numeric string"
}

Ответ
Анализируется HTTP-код ответа на запрос. В случае получения любого кода ответ отличного от 200, либо в случае таймаута запроса, запрос будет автоматически повторяться до получения успешного ответа. Т.е. до фактического приёма и обработки запроса партнёром.

Пример

Пример запроса
Callback URL_PS +URL_BZ/order?apikey=123
{ "id":"abcdefg", "fact_volume":"1.8","fact_amount":"78.34","fact_bill":"76.54"}

пример успешного ответа:
HTTP / 200 OK

пример неуспешного ответа:
HTTP / 400 ERROR

Уведомление об отмене заказа

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

(POST) URL_PS + /cancel?apikey={string}

Request body schema application/json

{
    "id": "string"
}

Ответ
Анализируется HTTP-код ответа на запрос. В случае получения любого кода ответ отличного от 200, либо в случае таймаута запроса, запрос будет автоматически повторяться до получения успешного ответа. Т.е. до фактического приёма и обработки запроса партнёром.

Пример

Пример запроса
Callback URL_PS +URL_BZ/order?apikey=123
{ "id":"abcdefg"}

пример успешного ответа:
HTTP / 200 OK

пример неуспешного ответа:
HTTP / 400 ERROR

Уведомление о формировании фискального чека

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

(POST) URL_PS + /receipt?apikey={string}

Request body schema application/json
{
    "id": "string",
    "receipt": "string"
}

Ответ
Независимо от полученного ответа, запрос выполняется один раз, без повторной отправки в случае получения ошибки.

Пример

Пример запроса
Callback URL_PS +URL_BZ/order?apikey=123
{ "id":"abcdefg", "receipt":"http://example.com"}

пример успешного ответа:
HTTP / 200 OK

пример неуспешного ответа:
HTTP / 400 ERROR