API-BENZUBER

Swagger API-Benzuber

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

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

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

• Получения информация о станции, её структуре ТРК и ценах на топливо;
• Проверки доступности станции;
• Постановки и обработки топливного заказа;

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

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

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

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

200 – запрос выполнен успешно
400 – станция не найдена, не верный идентификатор станции
401 – ошибка авторизации, доступ запрещен
404 – станция или ТРК не доступна, занята
500 – ошибка выполнения запроса, некорректные параметры запроса

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

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

200 – запрос выполнен успешно
Любой другой код – ошибка выполнения запроса

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

Используемые Коды топлива:

При обмене информацией между системами, применяется следующая система кодов видов топлива:

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

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

Запрос для получения информации о возможности работы партнера, а также доступного баланса партнёра в Benzuber.

Запрос

(GET) URL_BZ + /v1/balance/?apikey={apikey}

Ответ

Content type: application/json

{
  "Status": (string),
  "Balance": (double)
}

Получение информации о АЗС

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

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

/brands Получение информации по доступных брендах (сетях АЗС), с возможностью получения изображения логотипа сети.

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

/price Получение информации о ценах на топливо. Можно запросить как полный прайс по всем доступным станциям. Запрос можно выполнять несколько раз в сутки для поддержания актуального состояния цен у партнера. Либо можно запросить прайс по одной станции. Запрос можно выполнять при необходимости оперативного обновления цены по одной станции

/ping Получение информации о доступности станции. Рекомендуется использовать запрос перед приемом и установкой заказа

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

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

Запрос

(GET) URL_BZ + /v1/stations?apikey={apikey}&stationId={id}

Ответ

Content type: application/json

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

Получение названия сетей (брендов)

Получение информации по доступных брендах (сетях АЗС), с возможностью получения изображения логотипа сети.
Список брендов и изображения логотипов - очень статичная информация, и меняется редко. Поэтому рекомендуется при использовании запроса кэшировать данные на стороне партнёра, и обновлять данные при необходимости (например, при обнаружении нового бренда в списке АЗС, или при выявлении необходимости актуализации логотипа)

Запрос

(GET) URL_BZ + /v1/brands?apikey={apikey}&id={id}

Ответ

Content type: application/json

[
  {
    "id": "3",
    "name": "VARTA",
  },
  {"id":..., "name":...},
  ...
]

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

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

Запрос

(GET) URL_BZ + /v1/stations/{StationId}/columns?apikey={apikey}

Ответ

Content type: application/json

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

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

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

Запрос

(GET) URL_BZ + /v1/price?apikey={apikey}&stationId={id}

Ответ

Content type: application/json

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

Проверка статуса работы станции

Запрос для определения доступности и готовности ТРК на станции принять заказ.

Запрос

(GET) URL_BZ + /v1/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}

Обработка заказа

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

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

Запрос ORDER применяется для передачи партнёром нового заказа. Также запрос может быть использован для информирования о необходимости отмены заказа со стороны партнера, и для информирования партнёром о текущем статусе заказа в своей системе.

Запрос

(POST)URL_BZ + /v1/order?apikey={apikey}

Request body schema application/json

{
  "Id":(string),
  "DateCreate":(string),
  "Status":(string),
  "OrderType":(string),
  "OrderVolume":(double),
  "StationId":(string),
  "StationExtendedId":(string),
  "ColumnId":(int),
  "FuelId":(string),
  "PriceFuel":(double),
  "Litre":(double),
  "Sum":(double),
  "ExtendedId" : (string),
  "LitreCompleted":(double),
  "SumPaidCompleted":(double),
  "UserPhone":(string),
  "UserEmail":(string),
  "Loyalty":(string),
  "ContractId":(string),
  "DateEnd":(DateTime),
  "Reason":(string),
  "ReceiptURL":(string)
}

Ответ

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

200 – заказ получен, параметры корректны.
400 – станция не найдена (не верный идентификатор станции или ТРК)
402 – некорректная цена на топливо

При ответе сервера любым статусом, кроме 200, 400 и 402 или отсутствия ответа – партнер должен сделать несколько повторных попыток отправки запроса.

При получении заказа от партнера в статусе OrderCreated сервер Benzuber проверяет обязательные параметры и даёт код ответа:

• Код 400 – если идентификатор станции не найден в BZ
• Код 402 – в случае если стоимость топлива (PriceFuel) на станции отличает от присланной
• Код 200 – в остальных случаях

При получении заказа в статусе UserCanceled, сервер Benzuber пытается отменить заказ на станции. Если это удается, тогда партнеру передается запрос Canceled. Если такой запрос не поступил, значит отменить заказ не получилось (например, уже начался отпуск топлива)

Заказ в статусах Completed, StationCanceled может передаваться после завершения обработки заказа (перехода в финальный статус), для информирования о завершении обработки заказа у партнера.

Заказ в статусе Expire может передаваться, как информационный, в случае если состояние заказа неизвестно определённое время.

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

Возможность инициировать отмену ранее созданного заказа партнёром.
При получении от партнёра запроса на отмену заказа, сервер Benzuber пытается отменить заказ на станции. Если это удается, тогда партнеру передается callback-запрос Canceled.
Если такой запрос не поступил, значит отменить заказ не получилось (например, уже начался отпуск топлива).

Запрос

(GET) URL_BZ + /v1/order/cancel?apikey={apikey}&orderId={orderId}

Ответ

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

200 – запрос получен, будет выполнена попытка отмены заказа на АЗС.
401 – ошибка авторизации 
404 – заказ не найден (не верный идентификатор заказа)

В ответе на запрос отмены всегда возвращается актуальная информация по заказу, Ответ JSON структуры, как в запросе order

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

Запрос для получения актуальной информации по переданному ранее заказу. Ответ JSON структуры, как в запросе order

Запрос

(GET) URL_BZ + /v1/status?apikey={apikey}&orderId={orderId}

Верификации карты лояльности

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

Запрос

(GET) URL_BZ + /v1/loyalty/validation?provider={provider}&loyalty={loyalty}&apikey={apikey}

Ответ

Content type: application/json

{
  "status": "invalid",
  "message": "Недопустимый номер карты лояльности"
}

Передача состояния заказа партнеру

Сервер Benzuber выполняет запросы, для передачи статусов заказов партнеру на согласованный адрес:

URL_PS + /api/order/команда?apikey={apikey}&параметры

• Принятие заказа: команда Accept
• Готовность передачи заказа на АЗС: команда Fueling
• Завершение заказа: команда Completed
• Отмена заказа: команда Canceled
• Передача хода налива: команда Volume

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

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

Запрос

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

Ответ В случае если партнер дал ответ отличный от 200 ОК, то сервер Benzuber отсылает запрос Canceled и прекращает обработку заказ.

Подтверждение передачи на АЗС (Статус: fueling)

Запрос сообщает партнёру о том, что заказ готов к передачи на АЗС и сервер Benzuber готов передать команду на АЗС для запустка колонки (начать пролив).

Запрос

(GET) URL_PS + /api/order/fueling?apikey={apikey}&orderId={ordeId}

Ответ
В случае если партнер дал ответ отличный от 200 ОК, то сервер Benzuber отсылает запрос Canceled и прекращает обработку заказ.

Отмена заказа (Статус: canceled)

Запрос сообщает партнёру о том, что заказ не может быть исполнен и его следует отменить.

Запрос

(GET) URL_PS + /api/order/canceled?apikey={apikey}&orderId={ordeId}&reasonId={reason}&reason={reason}

Ответ
В случае если партнёр даёт ответ отличный от 200 ОК, то сервер Benzuber периодически, в течении некоторого времени, отсылает запросы повторно, до момента получения ответа 200 ОК

Таблица возможных кодов причины отмены заказа:

Завершение заказа (Статус: completed)

Запрос сообщает партнёру о том, что заказ выполнен и топливо залито.

Запрос

(GET) URL_PS + /api/order/completed?apikey={apikey}&orderId={ordeId}
                &litre={litre}&total={total}
                &extendedDate={extendedDate}&extendedOrderId={extendedOrderId}

Ответ
В случае если партнёр даёт ответ отличный от 200 ОК, то сервер Benzuber периодически, неограниченное количество времени, отсылает запросы повторно, до момента получения ответа 200 ОК

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

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

Запрос

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

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

Передача ссылки на фискальный чек

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

Запрос

(GET) URL_PS + /api/order/receipt?apikey={apikey}&orderId={ordeId}&receiptURL={url}

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

Тестовая среда, тестовая АЗС

Для тестовой среды реализована тестовая АЗС (stationId=10000). Эта АЗС выдается при получении списка АЗС.

На станции реализована возможность получения конфигурации, информации о ценах и постановка заказов.
Цены на топливо меняются раз в час