Benzuber
для партнеров
API Benzuber (electric) – протокол для обеспечения взаимодействия между внешней учетной системой партнера (PS) и сервером Benzuber (BZ).
Протокол позволяет партнёру осуществлять получение информации о доступных станциях электрозарядки, их структуре и тарифах, и выполнять операции необходимые для обеспечения старта зарядной сессии своих клиентов на этих станциях.
Для реализации взаимодействия партнёру необходимо реализовать запросы:
Для обеспечения безопасного доступа и идентификации партнера для работы с протоколом предоставляется уникальный ключ apikey, который используется во всех запросах.
Базовый URL_BZ – адрес для обращения к серверу BZ. Все запросы выполняются HTTPS запросами (GET или POST) вида: URL_BZ + /v1/charge/команда?apikey={apikey}
HTTP коды ответа:
200 – запрос выполнен успешно
400 – недопустимые параметры запроса
401 – ошибка авторизации, доступ запрещен
500 – ошибка обработки запроса
Базовый URL_PS – адрес для обращения к партнеру. Все запросы выполняются HTTPS запросами (GET или POST) вида: URL_PS + /api/charge/команда?apikey={apikey}
HTTP коды ответа:
200 – запрос выполнен успешно
Любой другой код – ошибка выполнения запроса
Для тестовой и продуктовой среды базовые адреса различные, и согласовываются с отделом разработки.
При обмене информацией между системами, применяется следующая система кодов коннекторов/подключений:
| Код - Название | Код - Название |
|---|---|
domestic_{x}бытовая розетка типа {x} |
gbt_acGB/T AC |
nema_6_{xx}разьем Нема-6 {xx}A |
gbt_dcGB/T DC |
nema_10_{xx}разьем Нема-10 {xx}A |
iec_62196_t1"Тип 1" |
nema_14_{xx}разьем Нема-14 {xx}A |
iec_62196_t1_comboCCS Combo 1 |
chademoCHArge de MOve |
iec_62196_t2"Тип 2" |
chaojiChaoJi/CHAdeMO 3.0 |
iec_62196_t2_comboCCS Combo 2 |
iec_60309_2_single_{nn}однофазный кабель на {nn}A |
iec_62196_t3a"Тип 3A" |
iec_60309_2_three_{nn}трехфазный кабель на {nn}А |
iec_62196_t3c"Тип 3C" |
pantograph_bottom_upпантограф (верхний) |
tesla_rпроприетарный разьем Tesla roadster |
pantograph_top_downпантограф (нижний) |
tesla_sпроприетарный разьем Tesla |
При работе партнёр может получить коды коннекторов, которые не указаны в таблице. Партнёр, должен реализовать автоматическую обработку такой ситуации для исключения ошибки обработки. Неизвестный код коннектора должен быть либо проигнорирован, либо обработан партнёром и включен в список актуальных кодов коннекторов.
При необходимости, партнёр может обратиться в Benzuber для согласования кодов коннекторов.
Для реализации взаимодействия предоставляются возможности:
/charge/list
Получение списка станций доступных партнеру. Рекомендуется запрашивать раз в сутки для актуализации полного списка, либо по необходимости.
/charge/{chargeId}/posts
Получение информации по станции, структура, доступность, тарификация. Рекомендуется запрашивать для получения оперативной информации о станции.
/charge/order
Постановка заказа на станцию.
/charge/cancel
Попытка отмены заказа.
/charge/status
Получение информации о заказе
Запрос
(GET) URL_BZ + /v1/charge/list?apikey={apikey}&chargeId={chargeId}| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| chargeId | string ID зарядной станции |
Ответ
Content type: application/json
[
{
"ChargeID": "Идентификатор",
"Name": "Название",
"Brand": "Название сети"
"City": "Город, регион",
"Address": "Адрес станции",
"Enable": true,
"Progress": false,
"Location":
{
"Lat":58.135324,
"Lon":45.693532
},
"MaxTotal": 10000
},
...
]Запрос
(GET) URL_BZ + /v1/charge/{chargeId}/posts?apikey={apikey}| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| Обязательный chargeId |
string ID зарядной станции |
Ответ
Content type: application/json
[
{
"PostId": "1",
"PostName": "111-457",
"PostFloor": "-1",
"PostStatus": "idle",
"PostOrderMin": "100.00",
"PostOrderMax": "1000.00",
"PostCapabilities":
{
"Charge": true,
"ChargeConnectorRequired": true,
"Reservation": false,
"Params": false
},
"PostConnectors": [],
},
...
]Элемент массива коннекторов (PostConnectors)
{
"ConnectorId": "1",
"ConnectorStandard": "gbt_dc",
"ConnectorFormat": "cable",
"ConnectorPowerType": "ac",
"ConnectorMaximums": {
"{x}" : {
"value": "60.00",
"unit": "{y}"
},
...
},
"ConnectorTariffs": {}
}Cтруктура тарифов (ConnectorTariffs)
{
"{t}": {
"Limit": {
"Minimum": "100.00",
"Maximum": "1000.00"
},
"Components": {
"{x}":[
{
"Price":"10.00",
"PriceFull":"12.00",
"PricePerUnit": "{y}",
"TariffStep": {
"Value": "24.00",
"Unit": "{z}"
},
"Restrictions": {
"{w}" :{
"From": "08:00",
"Till": "20:00",
"Unit": "{u}"
}
}
},
...
],
...
}
},
...
}Сценарий обработки заказа предполагает передачу информации о заказе от партнера, и передачу информации о ходе выполнения заказа от сервера Benzuber.
Создание заказа с необходимыми параметрами.
Запрос
(POST) URL_BZ + /v1/charge/order Request body schema application/json
{
"id": "f329g-3dsf-2dsf-dsgg",
"chargeId": "12345",
"mode": "charge",
"post": "2",
"connector": "1",
"period": "10",
"sum": "1500.00",
"userPhone": "79000000000",
"userEmail": "test@mail.ru",
"contractId": "b2b",
"apikey": "fdh32498"
}| Параметр | Описание |
|---|---|
| Обязательный id |
Строка Идентификатор заказа партнёра |
| Обязательный chargeId |
Строка Идентификатор зарядной станции |
| Обязательный mode |
Строка Тип заказа: charge - заказ на зарядку, reserve - заказ на бронирование |
| Обязательный post |
Строка Идентификатор поста |
| Обязательный connector |
Строка Идентификатор коннектора |
| Обязательный period |
Строка Период бронирования в минутах (в случае mode=reserve ) |
| Обязательный sum |
Строка Предельная стоимость заказа |
| userPhone | Строка телефон клиента для чека |
| userEmail | Строка e-mail клиента для чека |
| contractId | Строка Идентификатор договора |
| Обязательный apikey |
Строка API-ключ |
Ответ
HTTP коды ответа:
200 – заказ получен, параметры корректны.
401 - неверный Api-ключ
400 - недопустимые параметры запроса
403 - недопустимый заказ (зарядка/бронирование не поддерживаются, либо заказ на занятый пост)
404 - зарядная станция не найдена
503 - зарядная станция временно не доступна
500 - ошибка обработки запросаВозможность инициировать отмену ранее созданного заказа партнёром. При получении от партнёра запроса на отмену заказа, сервер Benzuber пытается отменить заказ на станции.
Запрос
(POST) URL_BZ + /v1/charge/cancel Request body schema application/json
{
"id": "f329g-3dsf-2dsf-dsgg",
"apikey": "fdh32498"
}| Параметр | Описание |
|---|---|
| Обязательный id |
Строка Идентификатор заказа партнёра |
| Обязательный apikey |
Строка API-ключ |
Ответ
HTTP коды ответа:
200 – заказ отменён, либо запрос пришел уже на отменный зазаз
202 - запрос на отмену зарегистрирован, в дальнейшем будет передан callback об отмене, либо завершении заказа, состояние заказа так же можно узнать из запроса состояния заказа
401 - неверный Api-ключ
400 - заказ отменить нельзя
404 - заказ не найден
500 - ошибка обработки запросаЗапрос для получения актуальной информации по переданному ранее заказу.
Запрос
(POST) URL_BZ + /v1/charge/status Request body schema application/json
{
"id": "f329g-3dsf-2dsf-dsgg",
"apikey": "fdh32498"
}| Параметр | Описание |
|---|---|
| Обязательный id |
Строка Идентификатор заказа партнёра |
| Обязательный apikey |
Строка API-ключ |
Ответ
HTTP коды ответа:
200 – успешный ответ, с информацией о заказе
401 - неверный Api-ключ
400 - неверные парамтеры заказа
404 - заказ не найден
500 - ошибка обработки запросаContent type: application/json
{
"id": "f329g-3dsf-2dsf-dsgg",
"Status": "Progress",
"ChargeStatus": "Charge",
"DateCreate": "2025-03-01T12:00:00",
"DateEnd": "2025-03-02T19:00:00",
"ChargeId": "12345",
"PostId": "1",
"Sum": "1500.00",
"SumCompleted": "1233.74",
"ChargeEnergy": "35,11",
"SumEnergy": "674.21",
"ChargeTime": "3.2",
"SumTime": "32",
"SumFixed": :"234",
"ParkingTime": "10",
"SumParking": "245",
"SumReservation": "331",
"ReasonId": "22",
"Reason": "Причина отмены заказа"
}Сервер Benzuber выполняет запросы, для передачи статусов заказов партнеру на согласованный адрес:
URL_PS + /api/charge/команда?apikey={apikey}&параметрыДанный запрос отправляет после того, как были произведены определённые действия с полученным заказом, проверено соответствие параметров, заказ сохранен в базе данных, и система готова перейти на следующий шаг. Запрос необходим, чтобы удостовериться что полученный заказ от партнёра действительный.
Запрос
(GET) URL_PS + /api/charge/accept?apikey={apikey}&orderId={ordeId}| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| Обязательный orderId |
Строка Идентификатор заказа партнёра |
Ответ
HTTP коды ответа:
200 – Заказ подтверждён партнером
любой другой код - запрос на подтверждение повторяется 5 раз с интервалом 5 секунд, затем отменяется. Устанавливается статус заказа = StationCanceledЗапрос сообщает партнёру информацию о ходе выполнения заказа
Запрос
(GET) URL_PS + /api/charge/processing?apikey=[apiKey]&orderId=[orderId]&chargeStatus=[chargeStatus]&amount=[amount]&energy=[energy]| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| Обязательный orderId |
Строка Идентификатор заказа партнёра |
| Обязательный chargeStatus |
Строка Статус выполнения заказа на станции: Wait , Charge , Reserve , Complete , Fail |
| amount | Строка Текущая стоимость оказанного объема услуг |
| energy | Строка Текущее значение электроэнергии в киловатт-часах |
| current | Строка Текущее значение тока зарядки в ампера |
| power | Строка Текущее значение мощности зарядки в киловаттах |
| percent | Строка Текущее значение уровня заряда автомобиля в процентах |
Ответ
HTTP коды ответа:
200 – Информация о ходе выполнения заказа принята партнёромЗапрос сообщает партнёру о том, что заказ выполнен.
Запрос
(GET) URL_PS + /api/charge/completed?apikey=[apiKey]&orderId=[orderId]&total=[total]&energy=[energy]&time=[time]| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| Обязательный orderId |
Строка Идентификатор заказа партнёра |
| Обязательный total |
Строка Итоговая стоимость завершенного заказа |
| Обязательный energy |
Строка Итоговое значение электроэнергии в киловатт-часах |
| time | Строка Итоговое значение полного времени оказания услуг в часах |
| parking | Строка Итоговое значение времени парковки в часах (когда не было зарядки) |
| total_fixed | Строка Итоговая стоимость фиксированных компонентов применяемого тарифа (не зависящих от объема) |
| total_energy | Строка Итоговая стоимость электроэнергии |
| total_time | Строка Итоговая стоимость времени зарядки |
| total_parking | Строка Итоговая стоимость времени парковки |
| total_reservation | Строка Итоговая стоимость времени резервирования |
Ответ
HTTP коды ответа:
200 – Информация о ходе выполнения заказа принята партнёром
любой другой код - уведомление о завершении заказа повторяется до получения ответа с кодом 200 с увеличивающимся интерваломЗапрос сообщает партнёру о том, что заказ не может быть исполнен и его следует отменить.
Запрос
(GET) URL_PS + /api/charge/canceled?apikey=[apiKey]&orderId=[orderId]&reason=[reason]&reasonId=[reasonId]| Параметр | Описание |
|---|---|
| Обязательный apikey |
Строка Ключ авторизации |
| Обязательный orderId |
Строка Идентификатор заказа партнёра |
| Обязательный reason |
Строка Описание причины отмены заказа |
| Обязательный reasonId |
Строка Код причины отмены заказа |
Ответ
HTTP коды ответа:
200 – Информация об отмене заказа принята партнёром
любой другой код - уведомление об отмене заказа повторяется до получения ответа с кодом 200 с увеличивающимся интерваломДля тестовой среды реализована тестовая АЗС (stationId=20000). Эта станция выдается при получении списка станций.