API-BENZUBER (goods)

API Benzuber (goods) – расширение протокола API-Benzuber для получения информации о предлагаемых на АЗС сопутствующих товарах, и возможности оформления заказа на покупку доступных товаров.

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

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

Получение информации о товарах

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

/stations Получение списка станций доступных партнеру, с указанием признака доступности товаров на станции.

/stations/{StationId}/goods Получение информации о доступных товарах на АЗС.

/stations/{StationId}/goods/image/{ProductImage} Получение изображение товара

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

Получение информации о станциях доступных для партнера, с указанием признака доступности товаров на станции.
В ответе содержится полный список доступны АЗС для партрёнра. Станции на которых доступны товары отмечены признаком IsGoods=true

Запрос

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

Ответ

Content type: application/json

[
  {
    "StationID": "Номер",
    ...
    "IsGoods": true,
    ...
  },
  {"StationID": ...},
  ...
]

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

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

Запрос

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

Ответ

Content type: application/json

[
  {
    "GroupName": "Капучино",
    "GroupImage": "23d4jh3",
    "GroupItems": [
      {
        "ProductId": "52",
        "ProductName": "Капучино S",
        "ProductDescr": "Вкуснейший Капучино (200 мл.)",
        "ProductUnit": "200 мл"
        "ProductImage" : "fd34dsf"
        "ProductPrice": "168.00"
      },
      ...
    ],
  },
  {"GroupName": ...},
  ...
]

Получение изображения товара

Получение файла с изображением товарной группы или товара.

Запрос

(GET) URL_BZ + /v1/stations/{StationId}/goods/image/{ProductImage}?apikey={apikey}

Ответ
Файл с изображением

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

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

Создание нового заказа на товары

Запрос PURCHASE применяется для передачи партнёром нового заказа на товары.

Запрос

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

Request body schema application/json

{
  "Id":(string),
  "StationExtendedId":(int),
  "Sum":(string),
  "Cart": [
    {
      "Id":(int),
      "Price": (string),
      "Quantity":(int),
      "Amount":(number)
    },
    ...
  ]
}

Ответ

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

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

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

• Код 400 – если идентификатор станции не найден
• Код 402 – в случае если цене товара (Price) на станции отличает от присланной,
• Код 500 - неверные параметры запроса, в т.ч. несовпадающая общая сумма заказа (Sum) с суммированием товарных позиций (Amount)
• Код 200 – в остальных случаях

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

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

Запрос

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

Ответ

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

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

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

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

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

• Принятие заказа: команда Accept
• Завершение заказа: команда Completed
• Отмена заказа: команда Canceled

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

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

Запрос

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

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

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

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

Запрос

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

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

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

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

Запрос

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

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

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

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

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