API-BENZUBER (с эквайрингом)

API Benzuber (с эквайрингом) – расширение протокола API-Benzuber для возможности проведения оплаты за топливо, используя эквайринговые возможности Benzuber.

Для реализации взаимодействия партнёру необходимо реализовать запросы:

• Авторизации пользователей партнёра в Benzuber;
• Управления привязками банковских карт пользователей;
• Постановки и обработка заказа;

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

Базовый URL_BZ – адрес для обращения к серверу Benzuber. Все запросы выполняются HTTP/HTTPS запросами (GET или POST) вида: URL_BZ + /команда/?apikey={apikey}

HTTP коды ответа:

200 – запрос выполнен успешно
401 – ошибка авторизации, доступ запрещен
4хх, 5хх – ошибка при выполнении запроса

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

{
    "error":string,  //идентификатор ошибки
    "error_description":string //описание ошибки
}

Работа с пользователями

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

Авторизация и информация о пользователе

/user/{phone}/init/ Инициирование авторизации пользователя по номеру телефона, отправка SMS сообщения пользователю для подтверждения

/user/{phone}/init/{pin}/ Передача полученного PIN-кода из SMS сообщения для подтверждения авторизации пользователя

/user/{authid}/state/ Получение информации о текущем статусе авторизации пользователя и списка доступных платежных средств

/user/{authid}/logout/ Удаление авторизации пользователя в сервисе Benzuber

Работа с платежными картами пользователя

/user/{authid}/card/attach/ Инициирование привязки банковской карты к профилю пользователя, с вызовом банковской формы для ввода реквизитов карты

/user/{authid}/card/attach/{attachid}/state/ Получение информации о состоянии инициированной ранее привязки банковской карты

/user/{authid}/card/{cardid}/remove/ Удаление привязанной карты из профиля пользователя

Работа с АЗС и заказами

Запросы по работе с АЗС и постановки заказа аналогичны запросам общего протокола API-Benzuber, с добавлением необходимых данных связанных с пользователем и его методом оплаты.

/stations/ Получение списка станций доступных партнеру, с гео-данными, доступными видами топлива и структурой ТРК на каждой станции.

/price/ Получение информации о ценах на топливо на всех доступных партнёру АЗС.

/stations/{stationid}/columns/ Получение информации по станции, структура и доступность колонок (ТРК), доступные виды топлива на каждой колонке и цены на топливо. Рекомендуется запрашивать для получения оперативной информации о станции.

/order/ Передача запроса на выполнение топливного заказа, с указанием пользователя и метода оплаты

/order/{orderid}/cancel/ Возможность инициировать отмену ранее созданного заказа партнёром.

/order/{orderid}/state/ Получение информации о ранее созданном заказе партнёра

Уведомления для партнера

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

/order/accept/ Подтверждение приёма заказа от партнёра

/order/volume/ Уведомление о текущем объеме налитого топлива, при выполнении заказа

/order/ Уведомление о текущем состоянии заказа

Работа с пользователями

Авторизация пользователя

Инициирование авторизации пользователя по номеру телефона, отправка SMS сообщения пользователю для подтверждения. У высланного кода установлен срок действия 10 минут. В случае повторной отправки запроса в этот период - новой SMS отправлено не будет, а в ответе будет информация о сроке действия высланного кода.

Запрос

(GET) URL_BZ + /user/{phone}/init/

Ответ

Content type: application/json

{
  "authExpiration": (string)
}

Возможные ошибки

Подтверждение PIN-кода

Передача полученного PIN-кода из SMS сообщения для подтверждения авторизации пользователя. В случае передачи верного кода, в ответ будет передан идентификатор пользователя authId, который используется в дальнейшем для идентификации пользователя.

Идентификатор является действующим в течение 30 дней, и автоматически продлевается при использовании сервиса пользователем.

Запрос

(GET) URL_BZ + /user/{phone}/init/{pin}/

Ответ

Content type: application/json

{
  "authId": (string),
  "isOrderAvailable" : (boolean),
  "userCards" : [
    {
        "id": (numeric),
        "title" : (string)
    },
    ...
  ]
}

Возможные ошибки

Информация о пользователе

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

Запрос

(GET) URL_BZ + /user/{authId}/state/

Ответ

Content type: application/json

{
  "clientPhone": (string),
  "isOrderAvailable" : (boolean),
  "userCards" : [
    {
        "id": (numeric),
        "title" : (string)
    },
    ...
  ]
}

Возможные ошибки

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

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

Запрос

(GET) URL_BZ + /user/{authId}/logout/

Ответ

Content type: application/json

{
  "status": "ok"
}

Работа с платежными картами пользователя

Привязка банковской карты

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

Запрос

(POST) URL_BZ + /user/{authId}/card/attach/

Request body schema application/json

{
    "return": (string)
}

Ответ

Content type: application/json

{
  "attachId": (string),
  "redirectUrl" : (boolean)
}

Возможные ошибки

Состояние процесса привязки карты

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

Запрос

(POST) URL_BZ + /user/{authId}/card/attach/{attachid}/state/

Ответ

Content type: application/json

{
  "status": (string)
}

Возможные ошибки

Удаление привязанной карты

Удаление привязанной карты из профиля пользователя

Запрос

(POST) URL_BZ + /user/{authId}/card/attach/{cardid}/remove/

Ответ

Content type: application/json

{
  "status": "ok"
}

Возможные ошибки

Работа с АЗС и заказами

Запросы по работе с АЗС и постановки заказа аналогичны запросам общего протокола API-Benzuber, с добавлением необходимых данных связанных с пользователем и его методом оплаты.

Получение списка АЗС и структуры ТРК

Получение информации о станциях доступных для партнера.

Запрос

(GET) URL_BZ + /stations/

Ответ

Content type: application/json

[
  {
    "StationID": "Номер",
    "Name": "Название",
    "Brand": "Название сети АЗС",
    "City": "Город, регион",
    "Address": "Адрес станции",
    "Postpay": false,
    "OrderBefore": false,
    "TakeBefore": false,
    "MaxTotal": 9990,
    "Fuels": [
              {
              "Id": "a92",
              "Marka": "АИ-92"
              },
              ...
            ], //fuels
    "Location":
        {
        "Lat": 56.839703,
        "Lon": 60.267601
        },
    "Columns":
        {"1": {"ColumnNumber":"1", "Fuels": ["a92","diesel"]},
        ...
        }
  },
  {"StationID": ...},
  ...
]

Получение прайс-листа

Запрос актуального списка цен на доступные виды топлива на станции.

Запрос

(GET) URL_BZ + /price/

Ответ

Content type: application/json

[
  {
    "StationId": "3",
    "ProductID": "a92",
    "Price": 42.43,
  },
  {"StationId":...},
  ...
]

Получение структуры ТРК на АЗС

Получение информации по станции, структура и доступность колонок (ТРК), доступные виды топлива на каждой колонке и цены на топливо.

Запрос

(GET) URL_BZ + /stations/{stationid}/columns/

Ответ

Content type: application/json

[
  {
    "ColumnId": "1",
    "ColumnNumber": "1",
    "ColumnLocked": false,
    "Products": [
      {
        "ProductId": "a92",
        "ProductName": "АИ-92",
        "ProductDescr": "АИ-92",
        "ProductPrice": 41.1,
        "IsTaken": true
      },
      ...
    ],
    "UnpaidOrder":
        {
          "ProductId":"a100_premium",
          "Litre":"12.80",
          "Sum":"659.07",
          "ExtendedId":"vmkl3y...s6freyfkz"
        }
  },
  {"ColumnId": ...},
  ...
]

Создание нового заказа

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

Запрос

(POST)URL_BZ + /order/

Request body schema application/json

{
  "authid":(string),
  "cardid":(string),
  "stationextendedid":(int),
  "columnid":(int),
  "fuelid":(string),
  "pricefuel":(double),
  "sum":(double),
  "extendedid":(string),
}

Ответ

Content type: application/json

{
  "orderId": (sting)
}

Возможные ошибки

Запрос на попытку отмены заказа

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

Запрос

(GET)URL_BZ + /order/{orderid}/cancel/

Ответ

Content type: application/json

{
  "status": (string)
}

Возможные ошибки

Запрос информации по заказу

Получение информации о ранее созданном заказе партнёра

Запрос

(GET)URL_BZ + /order/{orderid}/state/

Ответ

Content type: application/json

{
  "Id":(string),
  "Status":(string),
  "UserId":(string),
  "DateCreate":(string),
  "DateEnd":(string),
  "OrderType":(string),
  "OrderVolume":(string),
  "StationId":(string),
  "ColumnId":(int),
  "FuelId":(string),
  "FuelMarka":(string),
  "PriceFuel":(double),
  "Sum":(double),
  "Litre":(double),
  "SumPaidCard":(double),
  "SumPaid":(double),
  "LitreCompleted":(double),
  "SumPaidCardCompleted":(double),
  "SumPaidCompleted":(double),
  "ReasonId":(string),
  "Reason":(string),
  "Receipt":(string)
}

Возможные ошибки

Уведомления для партнера

При выполнении сценария обработки заказа, партнёр получает запросы-уведомления. URL_PS – адрес для обращения к серверу Партнёра, устанавливается в настройках интеграции.

Подтверждение заказа (Статус: accept)

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

Запрос

(GET) URL_PS + /order/accept?apikey={apikey}&orderId={orderId}

Ответ
В случае если партнер дал ответ отличный от 200 ОК, то заказ отменяется и обработка заказа завершается. В случае положительного ответа - происходит холдирование денежных средств на карте пользователя и заказ передается на АЗС

Передача состояния процесса налива

Выполнение запроса происходит с периодичностью от 2 до 5 секунд, по факту получения информации от АЗС. Ответ на запрос от партнера не контролируется, и повторно не отправляется. Некоторые АЗС не поддерживают передачу информации о ходе налива.

Запрос

(GET) URL_PS + /order/volume?apikey={apikey}&orderId={orderId}&&litre={volume}

Ответ
Ответ партнёра не учитывается при обработке запроса.

Уведомление о текущем состоянии заказа

Запрос для уведомления партнёра при изменении состояния заказа в ходе его обработки - при фактическом успешном наливе или отмене заказа.

Запрос

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

Ответ

Content type: application/json

{
  "Id":(string),
  "Status":(string),
  "UserId":(string),
  "DateCreate":(string),
  "DateEnd":(string),
  "OrderType":(string),
  "OrderVolume":(string),
  "StationId":(string),
  "ColumnId":(int),
  "FuelId":(string),
  "FuelMarka":(string),
  "PriceFuel":(double),
  "Sum":(double),
  "Litre":(double),
  "SumPaidCard":(double),
  "SumPaid":(double),
  "LitreCompleted":(double),
  "SumPaidCardCompleted":(double),
  "SumPaidCompleted":(double),
  "ReasonId":(string),
  "Reason":(string),
  "Receipt":(string)
}