Skip to main content

Chargers

Endpoints for managing chargers.

Registration process​

There are 2 ways of registering a charger in Hiven:

  1. Automatic Setup (only available in case of Wallbox chargers).

During this setup user is not required to do any manual actions in the myWallbox portal or Wallbox application.

  1. Manual Setup (available for any other charger brand).

During this setup user would have to log in to application provided by charger's manufacturer and manually configure OCPP connection details such as OCPP Server URL and Charge Point ID.

Automatic Setup​

Important note: Automatic Setup can only be used when users have Wallbox charger.

Step 1: Wallbox Login​

POST /v2/wallbox/register-account
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "username": "<string>",
  "password": "<string>"
}
  • username - Wallbox account username
  • password - Wallbox account password

Response

""

Read more

Step 2: GET Chargers​

GET /v2/wallbox/chargers
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

[
  {
    "id": "<number>",
    "uid": "<string>",
    "name": "<string>",
    "chargerType": "<string>",
    "image": "<string>",
    "lastConnection": "<string>",
    "lastSync": "<string>",
    "country": "<string>"
  }
]

Read more

Step 3: POST Register Charger​

POST /v2/hiven/devices/register-charger
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "name": "<string>",
  "vendor": "<string>",
  "vendorDeviceId": "<string>",
  "autoSetupOCPPConnection": "<boolean>"
}
  • name - name of the charger (retrieved from the Wallbox)
  • vendor - vendor of the charger (should be set to WALLBOX)
  • vendorDeviceId - id of the charger (retrieved from the Wallbox)
  • autoSetupOCPPConnection - property, which defines whether to set up OCPP connection to charger automatically or not (should be set to true in the automatic setup flow)

Response

""

Read more

Manual Setup​

Step 1: GET Steve URL​

Steve is an open-source OCPP server.

GET /v2/hiven/devices/steve-url
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "url": "<string>"
}

Read more

Step 2: POST Register Charger​

Create charger in Hiven with human-readable name.

POST /v2/hiven/devices/register-charger
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "name": "<string>"
}
  • name - name of the charger

Response

""

Read more

GET Chargers​

After the user has successfully added a charger to Hiven, you can retrieve a list of user's chargers.

GET /v2/hiven/devices?userId=:userId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

[
  {
    "id": "<string>",
    "type": "<string>",
    "integration": "<string>",
    "createdAt": "<string>",
    "attributes": {
      "name": "<string>",
      "partnerName": "<string>",
      "userId": "<string>",
      "externalId": "<string>",
      "connectorId": "<number>", // Optional
      "chargePoint": {
        "vendor": "<string>",
        "model": "<string>",
        "serialNumber": "<string>"
      }, // Optional
      "chargeBox": {
        "id": "<string>",
        "ocppProtocol": "<string>",
        "registrationStatus": "<string>"
      } // Optional
    },
    "settings": {
      "chargingPreferences": {
        "chargingBehavior": "<string>", // Optional
        "locationId": "<string>", // Optional
        "readyTime": "<string>", // Optional
        "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
        "associatedDeviceId": "<string>", // Optional
        "minimumEnergyTransfer": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "targetEnergyTransfer": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "targetSoC": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "minimalSoC": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "spotPriceAreaId": "<string>" // Optional
      } // Optional
    }
  }
]

Important note: This call returns also other device types (E.g. vehicles) if they are added to Hiven, but they are documented separately.

  • type - device type, in case of charger always equals to EV_CHARGER
  • integration - device integration, in case of charger always equals to OCPP
  • createdAt - device creation time (in UTC)

Read more

GET Charger Details​

Retrieve charger details.

GET /v2/hiven/devices/:chargerId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "id": "<string>",
  "type": "<string>",
  "integration": "<string>",
  "createdAt": "<string>",
  "attributes": {
    "name": "<string>",
    "partnerName": "<string>",
    "userId": "<string>",
    "externalId": "<string>",
    "connectorId": "<number>", // Optional
    "chargePoint": {
      "vendor": "<string>",
      "model": "<string>",
      "serialNumber": "<string>"
    }, // Optional
    "chargeBox": {
      "id": "<string>",
      "ocppProtocol": "<string>",
      "registrationStatus": "<string>"
    } // Optional
  },
  "settings": {
    "chargingPreferences": {
      "chargingBehavior": "<string>", // Optional
      "locationId": "<string>", // Optional
      "readyTime": "<string>", // Optional
      "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
      "associatedDeviceId": "<string>", // Optional
      "minimumEnergyTransfer": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "targetEnergyTransfer": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "targetSoC": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "minimalSoC": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "spotPriceAreaId": "<string>"
    } // Optional
  }
}

Read more

DELETE Charger​

Remove charger from Hiven.

DELETE /v2/hiven/devices/:chargerId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

""

Read more

PUT Charging Preferences​

Set charging preferences to be used when creating smart charging session.

Important note: Even though it is PUT, it acts as a PATCH allowing partial updates.

PUT /v2/hiven/devices/:chargerId/smart-charging/ocpp-charger-preferences
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "chargingBehavior": "<string>", // Optional
  "locationId": "<string>", // Optional
  "readyTime": "<string>", // Optional if "chargingBehavior" is "SMART_CHARGE_OFF"
  "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
  "associatedDeviceId": "<string>", // Optional
  "minimumEnergyTransfer": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "targetEnergyTransfer": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "targetSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional if "chargingBehavior" is "SMART_CHARGE_OFF"
  "minimalSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "spotPriceAreaId": "<string>" // Optional
}

  • chargingBehavior - charging session behavior

    • SMART_CHARGE_ON - Smart Charging is enabled
    • SMART_CHARGE_OFF - Smart Charging is disabled, the car will start charging immediately

  • locationId - charging location id configured for a given charger

Important note: To retrieve an id of a charging location, it must be created in Hiven. Follow the instructions here.

  • readyTime - time until when the charging session should be completed (in HH:mm local time format)
  • weekDaySpecificReadyTimes - time until when the charging session should be completed defined per each day of the week (in HH:mm local time format)

Important note: Either readyTime or weekDaySpecificReadyTimes should be set in order to properly calculate charging schedule. Both of them can be configured at the same time but when weekDaySpecificReadyTimes is specified, it will take precedence over the readyTime.

An example of readyTime:

{
  "readyTime": "08:00"
}

An example of weekDaySpecificReadyTimes:

{
  "weekDaySpecificReadyTimes": {
    "MONDAY": "08:00",
    "TUESDAY": "08:00",
    "WEDNESDAY": "08:00",
    "THURSDAY": "08:00",
    "FRIDAY": "08:00",
    "SATURDAY": "12:00",
    "SUNDAY": "18:00"
  }
}

Not all days of the week are required, you can skip some of them if needed.

In case if a day is skipped, Hiven will use readyTime value as a fallback.

  • spotPriceAreaId - id of the spot price area Hiven should take electricity prices from (for example SE3 for Sweden market)

  • associatedDeviceId - id of the vehicle which is associated with the charger

When charger is not associated to vehicle (associatedDeviceId is not set)​

  • minimumEnergyTransfer - minumum amount of energy that should be transfered regardless of the electricity prices

    • value - numeric value for given unit
    • unit - energy transfer unit (kWh)

  • targetEnergyTransfer - target amount of energy that should be transfered to the vehicle during smart charging session

    • value - numeric value for given unit
    • unit - energy transfer unit (kWh)

When charger is associated to vehicle (associatedDeviceId is set)​

  • minimalSoC - minumum number of % that vehicle should be charged regardless of the electricity prices

    • value - numeric value for given unit
    • unit - energy transfer unit (PERCENT)

  • targetSoC - target number of % that vehicle should be charged during smart charging session

    • value - numeric value for given unit
    • unit - energy transfer unit (PERCENT)

Response

""

Read more

Vehicle Association​

A vehicle can be associated to a charger in order for the charger to be able to read vehicle's state of charge.

Association can be done by setting associatedDeviceId property while saving charger preferences:

{
  "associatedDeviceId": "<string>",
  "targetSoC": {
    "value": "<number>",
    "unit": "<string>"
  },
  "minimalSoC": {
    "value": "<number>",
    "unit": "<string>"
  },
}

When an association is done, Hiven expects targetSoC and minimalSoC in the payload instead of targetEnergyTransfer and minimumEnergyTransfer and the reason is - when vehicle is associated, Hiven can read vehicle's current state of charge and steer charging process using percentages (e.g. vehicle has 50%, user set the target charge level to 80%, Hiven chargers to 80% according to the schedule when it's cheapest).

Othwerise, if vehicle is not associated, Hiven can steer by the amount of kWh charger should transfer to the vehicle (e.g. user wants to transfer 50kWh from charger to vehicle).

Important note: Hiven needs to know the battery capacity of the vehicle in order to accurately calculate time to full charge for the vehicle.

Battery capacity is usually returned in a telemetry for a vehicle, but in some rare cases it can be null.

When it's null, battery capacity should be explicitly requested from the user and sent to Hiven in an API call for setting vehicle preferences.

Hiven always reads battery capacity from vehicle telemetry first. If it's not set - Hiven searches for it in vehicle preferences. This means that a battery capacity specified in telemetry always has precedence over battery capacity in vehicle preferences (It's possible to have it specified in both places).

GET Charging Preferences​

Retrieve charging preferences.

GET /v2/hiven/devices/:chargerId/smart-charging/ocpp-charger-preferences
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "chargingBehavior": "<string>", // Optional
  "locationId": "<string>", // Optional
  "readyTime": "<string>", // Optional
  "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
  "associatedDeviceId": "<string>", // Optional
  "minimumEnergyTransfer": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "targetEnergyTransfer": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "targetSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "minimalSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "spotPriceAreaId": "<string>" // Optional
}

Read more

GET Charger Status​

Retrieve charger telemetry.

GET /v2/hiven/devices/ocpp-charger/:chargerId/status
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "vendorId": "<string>",
  "statusTimestamp": "<string>",
  "heartbeatTimestamp": "<string>",
  "errorCode": "<string>",
  "vendorErrorCode": "<string>",
  "firmwareVersion": "<string>",
  "measurement": {
    "timestamp": "<string>",
    "value": "<number>",
    "unit": "<string>"
  } | null,
  "status": "<string>"
}
  • status - current charging status

All possible values:

  • AVAILABLE - ChargeBoxID was last Online, Cable is DISCONNECTED from Vehicle
  • PREPARING - ChargeBoxID was last Online, Cable is CONNECTED to Vehicle but NOT CHARGING
  • CHARGING - ChargeBoxID was last Online, Cable is CONNECTED to Vehicle as well as CHARGING
  • SUSPENDED_EVSE - ChargeBoxID was last Online, Cable is CONNECTED to Vehicle but NOT CHARGING
  • SUSPENDED_EV - ChargeBoxID was last Online, Cable is CONNECTED to Vehicle but NOT CHARGING
  • FINISHING - ChargeBoxID was last Online, Cable is CONNECTED to Vehicle but COMPLETED/NOT CHARGING
  • RESERVED - ChargeBoxID was last Online, Cable is CONNECTED+NotCharging or DISCONNECTED
  • UNAVAILABLE - ChargeBoxID was last Online, Cable is CONNECTED+NotCharging or DISCONNECTED
  • FAULTED - ChargeBoxID was last Online, Cable is CONNECTED+NotCharging or DISCONNECTED

Conditions:

"measurement" is "null"​

status field can't contain CHARGING.

"measurement" is provided (not "null")​

status field equals to CHARGING.

Read more