Skip to main content
v5.33
Last updated on

API Reference

API docs by Redocly

ebee Charge Controller REST API (v1.0)

Download OpenAPI specification:Download

Note: All API endpoints are prefixed with /v1

OpenAPI 3.0 spec

REST API v1.0 of ebee Charge Controllers – OpenAPI 3.0 specification

Overview

This specification describes the REST API v1.0 provided by an ebee/Bender charge controller to be accessed by a web interface in a browser or a smart phone application.

The main use cases based on this API are:

  • configurating the charge controller / charge point
  • inquiring state information about the charge controller / charge point
  • obtaining information about past charging transactions
  • additional use cases

The API is based on the client-server principle. The charge controller acts as a server and the web interface or smart phone app acts as a client.

The API may be accessed via two alternative protocol stacks, one being HTTP(S) in TCP/IP networks such as Ethernet or WiFi, the other one being an NFC based protocol stack of an NFC equipped smart phone.

The request and response messages are encoded in JSON format. This specification provides examples of such messages.

The JSON UTF8 content is mapped to the two alternative protocol stacks. The actual request and response message content is identical for both protocol stacks. However the header information is transmitted slightly different in the HTTP(S) and in the NFC stack.

NFC Mapping

To access the API from an NFC equipped smart phone, the charge controller emulates an NFC Type 4 Tag based on the following standards:

  • Transmission: ISO 14443 A
  • Data Interchange: ISO 7816-4
  • Data Container: NDEF – NFC Data Exchange Format – Text Record Type Messages

Activation

The RFID reader used can be operated in two modes:

  • RFID only: only RFID cards can be read
  • RFID/NFC hybrid: NFC communication is supported and RFID cards can be read

Since the basic functionality of a charger is reading RFID cards, the default mode of the reader is RFID only.

Switching the reader into the RFID/NFC hybrid mode has to be done via the charge point's web interface by logging in as operator. The parameter RFID Mode can be found in the AUTHORIZATION view in section RFID Settings and needs to be set accordingly.

In RFID/NFC hybrid mode, the reader checks for both RFID and NFC communication until one of them is detected, afterwards this one will automatically be used. In case of NFC this means emulating an NFC Type 4 Tag which will be used for the data interchange between smart phone and charge controller via read/write operations.

Once NFC communication is established, the user interface of the charge point will display the corresponding pattern of the HMI state "Reading card".

After one minute of inactivity, the RFID reader will switch back to RFID/NFC checking and the HMI will transition to the appropriate HMI state which is depending on the charger state.

Request/Response messaging

The NDEF text messages provide a transport for messages including transmitting their length. This protocol therefore does not need to transmit length information in the header like the HTTP protocol does.

However, some header information needs to be transmitted in this transport which is otherwise not provided by the NDEF infrastructure. This includes the URL endpoint path which defines the service type, the HTTP method, the authorization info for the running login session, and a message id.

To provide a replacement for the HTTP header information, in NDEF a separate JSON based header is transmitted for request messages. An example request header looks like this:

{
  "path": "/settings",
  "method" : "POST",
  "authorization" : "cdc630cd-5e5f-4587-8a1a-a2e83ae990b5",
  "messageID" : "msg-id-increment"
}

The protocol allows for only one outstanding request message. Pipelining multiple messages is not allowed. It is therefore unambiguously clear which response message belongs to which request message. The response header contains the message id and a status code to replicate functionality otherwise provided by the HTTP header. An example response header looks like this:

{
  "messageID": "msg-id-increment",
  "statusCode": 401
}

Both in request and response messages an optional content JSON document may follow the header. If such JSON document exists, it is separated from the header by a comma (ASCII character 0x2C). In request messages which are fully defined by the request header (e.g. using the GET method) no content document is needed. In response messages which do not provide any content as a response (such as the equivalent of an HTTP error message) no content JSON object is transmitted.

The status code returned from the server is equivalent to the HTTP response code that would be used according to REST principles.

The message id, which is defined by the client, is recommended to be a number which is incremented between consecutive messages (and not randomized) to ease detecting bugs when analyzing logs.

Login and session authorization

The REST API is password protected, the user of the API needs to authenticate.

The login endpoint path /login is used first, only this endpoint is available without login credentials. All other API calls require a successful login with valid login credentials and the provision of a valid regular authorization info, the session id, during a login session.

The general procedure is: (Details are described below in section App User Authentication.)

Use the login endpoint with the GET method to obtain a login token from the server. The response will contain a login token which afterwards shall be used to hash the password for the subsequent actual login operation using the POST method. This token is valid only for one (the subsequent) login attempt. Each token becomes invalid after the login attempt is executed or when the next token is requested.

Use the login endpoint with the POST method to perform the actual login operation. The POST request payload shall contain the username as well as the password which is concatenated with the received token and afterwards hashed using the SHA-256 algorithm. The response will contain a login status and, in case of success, a session id which indicates the beginning of a login session.

This session id has to be included in the authorization info of all subsequent API calls. In case of HTTP(S) usage the session id is included in the HTTP 'Authorization' header, in case of NFC mapping the session id is included in the corresponding 'authorization' entry of the separate JSON header.

The session id will time out after 60 seconds without any further API calls. Therefore it is essential to actively keep the login session alive or to automate subsequent logins. The response code to any API call with an invalid or timed out session id will be '401 Unauthorized'.

Logout

The logout endpoint path /logout is used last in order to terminate a login session after a user of the API was logged in.

Use the logout endpoint with the POST method to perform the logout operation. (Details are described below in section App User Authentication.)

The session id will become invalid after the logout operation is executed.

App User Authentication

Authenticate the app user when accessing the charge controller via app, start or terminate a user session.

[/v1/login] Get a (one-time) token to hash the login password Deprecated

Full endpoint path: /v1/login

Get a login token which may be used once to hash the password for the actual login.

The token is valid only for one (the subsequent) login attempt. It becomes invalid when the login attempt is executed, or when the next token is requested.

Responses

Response Schema: application/json
token
required
string

Generated 32 characters random string, valid for one POST /login request

Response samples

Content type
application/json
{
  • "token": ">2BGLs|@|TIYOi3@5kTvQRZg$xL<rh3V"
}

[/v1/login] Perform the login on the charge controller Deprecated

Full endpoint path: /v1/login

Perform the actual login and start a user session. Each login attempt will need a new login token.

Request Body schema: application/json
required

Send login credentials (username and SHA-256 hash of password concatenated with the login token)

Important: A new token is required for each login attempt.

username
required
string

The plain username

password
required
string <SHA-256 hash>

The SHA-256 hash calculated for the concatenation of the plain password and the login token received before, e.g. by means of the crypto-js function sha256():

sha256(plain_password + login_token).toString()

Responses

Response Schema: application/json
logged_in
required
boolean

The login status, here true

required
object
id
required
string <UUID> (SessionId)

The returned session id for the running user session

Response samples

Content type
application/json
{
  • "logged_in": true,
  • "session": {
    • "id": "cdc630cd-5e5f-4587-8a1a-a2e83ae990b5"
    }
}

[/v1/logout] Perform the logout from the charge controller

Full endpoint path: /v1/logout

Perform the logout and terminate the user session.

Authorizations:
sessionIdAuth

Responses

Response samples

Content type
application/json
{
  • "logged_in": false,
  • "message": "Not logged in",
  • "code": 1002
}

Settings Parameters

View and edit the settings parameters of the charge controller.

[/v1/settings] Get all or specific settings parameters

Full endpoint path: /v1/settings

Get all settings parameters of the charge controller, or specific settings parameters.

Optionally, specify the desired settings parameters by their key names in a 'params' URL query (recommended) or in a request body (deprecated, should no longer be used.) The response will only return each specified settings parameter and its value.

If no specific key names are given, the response will return all setting parameters. The response will also include meta info for each settings parameter like parameter type, read/write mode, short and long description, default value.

Authorizations:
sessionIdAuth
query Parameters
params
string
Example: params=Enabled_wlan,WebUIStyle_web,SysTime_mon

A list of comma-separated key names to specify the desired settings parameters that shall be fetched

The URL query may have a maximum size of 4000 characters including the commas.

The URL query is recommended, preferred to a request body.

(optional - omit the query to get all settings parameters)

Request Body schema: application/json
optional

An array of key names to specify the desired settings parameters that shall be fetched

The request body should no longer be used, preferably use an URL query.

(optional - omit the request body to get all settings parameters)

params
Array of strings

The parameter keys that shall be fetched

Responses

Response Schema: application/json
One of
name
required
string

Name of the response object, always 'settings'

required
object
reboot_required
required
boolean

States if the charge controller has to be rebooted due to a previously changed value

required
Array of objects (Group)

Array of groups of settings parameters

Array
role
string
Enum: "dev" "manufacturer" "operator" "user" "installer" "manufacturer+" "operator+" "user+" "installer+"

User access level of the group

The access level is related to the app user currently logged in. The lowest access level is 'installer', the highest access level is 'dev' (developer).

A '+' behind the role name includes all other roles having a higher access level.

key
required
string
Enum: "network" "backend" "authorization" "whitelists" "loadmanagement" "installation" "system" "devel"

Unique key name of the group

The key names are machine-readable identifiers of the groups.

label
required
string
Enum: "Network" "Backend" "Authorization" "Whitelists" "Load Management" "Installation" "System" "Development"

Label of the group

The labels are human-readable identifiers of the groups.

required
Array of objects (SubGroup)

Array of subgroups of settings parameters

required
object (ChargePointInfo)

Additional info on the chargepoint features

required
Array of objects

The translation languages offered by the chargepoint

Array
key
required
string
Enum: "gb" "de" "nl" "fr"

The key name of a language

value
required
integer

The enum value of a language

lang
required
string
Enum: "en_GB" "de_DE" "nl_NL" "fr_FR"

The ISO language code of a language

label
required
string
Enum: "English" "Deutsch" "Nederlands" "Français"

The name of a language

active
boolean

Marks the language currently active, i.e. selected by the app user.

MultipleConnectors
required
boolean

States if the chargepoint features more than one connector

ControllerHemX2
required
boolean

States if the charge controller hardware is a HEM-X2 variant

OCPPWLEnabled
required
boolean

States if the OCPP whitelist is enabled

FLLEnabled
required
boolean

States if the local whitelist is enabled

Response samples

Content type
application/json
Example
{
  • "name": "settings",
  • "result": {
    • "reboot_required": false
    },
  • "groups": {
    • "0": {
      },
    • "1": {
      },
    • "2": "..."
    },
  • "ChargePointInfo": {
    • "languages": {
      },
    • "MultipleConnectors": false,
    • "ControllerHemX2": false,
    • "OCPPWLEnabled": true,
    • "FLLEnabled": true
    }
}

[/v1/settings] Set specific settings parameters

Full endpoint path: /v1/settings

Set specific settings of the charge controller. Specify the desired settings parameters by their key names and their new values in the request body.

Authorizations:
sessionIdAuth
Request Body schema: application/json
required

The key names and new values of the settings parameters to be set

params
required
Array of objects

The parameter key names and their new values that shall be set

Responses

Response Schema: application/json
params
required
Array of objects

The parameter key names and their setting success infos

reboot_required
required
boolean

States if the charge controller has to be rebooted due to a changed value

Response samples

Content type
application/json
{
  • "params": {
    • "0": {
      },
    • "1": {
      }
    },
  • "reboot_required": true
}

[/v1/settings] Set specific settings parameters, including parameter validation

Full endpoint path: /v1/settings

Set specific settings of the charge controller. Specify the desired settings parameters by their key names and their new values in the request body.

Additionally perform a validation process on each parameter key before any data is written. If one of the validation steps fails for at least one key, no data will be written.

Validation steps:

  • check the JSON format of each key/value pair: {"key": "Param_key", "value": new_value}
  • check if the app user currently logged in is allowed to change the parameter key
  • check if the parameter key is found
  • check if the value type is correct for the given parameter key
Authorizations:
sessionIdAuth
Request Body schema: application/json
required

The key names and new values of the settings parameters to be validated and set

params
required
Array of objects

The parameter key names and their new values that shall be set

Responses

Response Schema: application/json
params
required
Array of objects

The parameter key names and their setting success infos

reboot_required
required
boolean

States if the charge controller has to be rebooted due to a changed value

Response samples

Content type
application/json
{
  • "params": {
    • "0": {
      },
    • "1": {
      }
    },
  • "reboot_required": true
}

Charging Transactions

Information on charging transactions

[/v1/transactions] Get infos on completed charging transactions in detail

Full endpoint path: /v1/transactions

Get detailed infos on all completed transactions.

This will include only completed transactions. For incomplete transactions see the /transactions/active call or the /system_state call.

These infos may be fetched for all transactions in the database, or only for the transactions within a specified timespan via 'from' and 'to' URL queries. If the 'to' query is omitted, only the 'from' query will be evaluated and all results until now will be included.

Authorizations:
sessionIdAuth
query Parameters
from
string <UTC date-time>
Example: from=2019-11-23T19:35:43.511Z

The beginning of a specified timespan

to
string <UTC date-time>
Example: to=2019-11-24T19:35:43.511Z

The end of a specified timespan

Responses

Response Schema: application/json
Array
transactionId
required
string <UUID>

The unique transaction identifier of the transaction

backendTransactionId
string

The unique transaction identifier of the transaction set by the backend

tagId
string

The tag identifier used for the transaction

userId
string <UUID>

The user identifier associated with the transaction

startTransaction
required
string <UTC date-time>

The beginning timestamp of the transaction

endTransaction
required
string <UTC date-time>

The end timestamp of the transaction

consumption
required
integer

The energy in Wh consumed during the transaction

maxPower
required
integer

The maximum charging power in W during the transaction

Response samples

Content type
application/json
{
  • "0": {
    • "transactionId": "4cd1855c-4492-67ea-898f-98uz8ce881qw",
    • "backendTransactionId": "123456",
    • "tagId": "0102b0a5fd",
    • "userId": "c9228f30-daa2-4a24-b9c0-e38aa2dc3fes",
    • "startTransaction": "2019-11-23T19:35:43.511Z",
    • "endTransaction": "2019-11-24T19:35:43.511Z",
    • "consumption": 2935,
    • "maxPower": 11000
    },
  • "1": "..."
}

[/v1/transactions/summary] Get a summary of completed transactions

Full endpoint path: /v1/transactions/summary

Get a summary of all completed transactions.

This summary may be fetched for all transactions in the database, or only for the transactions within a specified timespan via 'from' and 'to' URL queries.

Authorizations:
sessionIdAuth
query Parameters
from
string <UTC date-time>
Example: from=2019-11-23T19:35:43.511Z

The beginning of a specified timespan

to
string <UTC date-time>
Example: to=2019-11-24T19:35:43.511Z

The end of a specified timespan

Responses

Response Schema: application/json
transactionCount
required
integer

The number of completed transactions

totalDuration
required
integer

The total duration in s of the transactions

totalConsumption
required
integer

The total energy in Wh consumed during the transactions

Response samples

Content type
application/json
{
  • "transactionCount": 12,
  • "totalDuration": 2375,
  • "totalConsumption": 148
}

[/v1/transactions/active] Check if a transaction is running

Full endpoint path: /v1/transactions/active

Check if an active (incomplete) transaction is currently running.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
success
required
boolean

Success of the operation, here true

Response samples

Content type
application/json
{
  • "success": true
}

Chargepoint Users Identity

Identity of chargepoint users and cars (mappings between user names and unique user ids)

[/v1/users] Get all users from the database

Full endpoint path: /v1/users

Get a list of all existing users from the database. Each list entry contains a user name associated with a unique user id in UUID format.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
Array of objects (User)
Array
userId
required
string <UUID>

The unique user identifier

userName
required
string

The user name

Response samples

Content type
application/json
{
  • "users": {
    • "0": {
      },
    • "1": {
      },
    • "2": "..."
    }
}

[/v1/users] Add a new user to the database

Full endpoint path: /v1/users

Add one new user to the database. Specify a new user name, a new associated unique user id in UUID format will be returned.

Maximum user name length is 255 characters.

Authorizations:
sessionIdAuth
Request Body schema: application/json
required
userName
string

The new user name

Responses

Response samples

Content type
application/json
{
  • "userId": "45d3711a-2acd-5812-cb44-f23fa3b791c2",
  • "userName": "Jenny"
}

[/v1/users/{userId}] Get one existing chargepoint user from the database

Full endpoint path: /v1/users/{userId}

Get one existing chargepoint user from the database specified by its user id.

Authorizations:
sessionIdAuth
path Parameters
userId
required
string <UUID>
Example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes

The user id of the chargepoint user that needs to be retrieved

Responses

Response Schema: application/json
userId
required
string <UUID>

The unique user identifier

userName
required
string

The user name

Response samples

Content type
application/json
{
  • "userId": "c9228f30-daa2-4a24-b9c0-e38aa2dc3fes",
  • "userName": "Alex"
}

[/v1/users/{userId}] Modify one existing chargepoint user in the database

Full endpoint path: /v1/users/{userId}

Modify the user name of an existing chargepoint user in the database specified by its user id.

Maximum user name length is 255 characters.

Authorizations:
sessionIdAuth
path Parameters
userId
required
string <UUID>
Example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes

The user id of the chargepoint user that needs to be modified

Request Body schema: application/json
required
userName
string

The changed user name

Responses

Response Schema: application/json
success
required
boolean

Success of the operation, here true

Response samples

Content type
application/json
{
  • "success": true
}

[/v1/users/{userId}] Delete one existing chargepoint user from the database

Full endpoint path: /v1/users/{userId}

Delete an existing chargepoint user from the database specified by its user id.

Authorizations:
sessionIdAuth
path Parameters
userId
required
string <UUID>
Example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes

The user id of the chargepoint user that needs to be deleted

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "cause": "invalid path"
}

Whitelisting

Handle the (local) whitelist of chargepoint users and cars authorised for charging. Possible ids include RFID tags, EVCCIDs, and NFC.

[/v1/whitelist] Get all whitelist entries

Full endpoint path: /v1/whitelist

Get all entries of the local whitelist.

Authorizations:
sessionIdAuth
query Parameters
type
required
string
Example: type=local

The whitelist type - only the 'local' whitelist is supported.

Responses

Response Schema: application/json
success
boolean

Success of the operation, here true

Array of objects (WhitelistEntry)
Array
id
required
string

The tag used to identify the local whitelist entry

tagType
string
Enum: "RFID" "EVCCID" "NFC"

The tag type (RFID, EVCCID, or NFC)

number
integer

An optional alias number for the 'id' tag, specified by the chargepoint user

name
string

An optional alias name for the 'id' tag, specified by the chargepoint user

userid
string <UUID>

A user id belonging to the local whitelist entry

priority
string
Enum: "NORMAL" "HIGH"

The priority of the local whitelist entry (normal/high)

Response samples

Content type
application/json
{
  • "success": true,
  • "tags": {
    • "0": {
      },
    • "1": "..."
    }
}

[/v1/whitelist] Add or edit specific whitelist entries, or clear all whitelist entries

Full endpoint path: /v1/whitelist

Add new entries to the local whitelist, or edit existing entries of the local whitelist. One or multiple tag(s) may be added/edited within the same request.

Or clear all local whitelist entries.

Authorizations:
sessionIdAuth
Request Body schema: application/json
required
type
required
string

The whitelist type - only the 'local' whitelist is supported.

command
required
string
Enum: "add" "edit" "clear"
Array of objects (WhitelistEntry)

The whitelist entries that shall be added or edited (not needed in case of command 'clear')

Array
id
required
string

The tag used to identify the local whitelist entry

tagType
string
Enum: "RFID" "EVCCID" "NFC"

The tag type (RFID, EVCCID, or NFC)

number
integer

An optional alias number for the 'id' tag, specified by the chargepoint user

name
string

An optional alias name for the 'id' tag, specified by the chargepoint user

userid
string <UUID>

A user id belonging to the local whitelist entry

priority
string
Enum: "NORMAL" "HIGH"

The priority of the local whitelist entry (normal/high)

Responses

Response Schema: application/json
success
required
boolean

Success of the operation, here true

Response samples

Content type
application/json
{
  • "success": true
}

[/v1/whitelist] Delete specific whitelist entries

Full endpoint path: /v1/whitelist

Delete existing entries of the local whitelist. One or multiple tag(s) may be deleted within the same request.

Specify the desired whitelist entries by their tag id's in an URL query (recommended) or in a request body (deprecated, should no longer be used.)

Authorizations:
sessionIdAuth
query Parameters
type
string
Example: type=local

The whitelist type - only the 'local' whitelist is supported.

ids
string
Example: ids=abcdef12,abcdef34,abcdef56

A list of comma-separated tag id's to specify the desired whitelist entries that shall be deleted

The URL query may have a maximum size of 1000 characters including the commas.

The URL query is recommended, preferred to a request body.

Request Body schema: application/json
optional

Parameters to specify the desired whitelist entries that shall be deleted

The request body should no longer be used, preferably use an URL query.

type
required
string

The whitelist type - only the 'local' whitelist is supported.

command
required
string

The command, always 'delete'

required
Array of objects (WhitelistTag)

The 'id' tag(s) that shall be deleted

Array
id
required
string

The tag used to identify the local whitelist entry

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "cause": "missing parameter 'tags'"
}

[/v1/whitelist/pairing] Enable the whitelist pairing mode

Full endpoint path: /v1/whitelist/pairing

Enable the whitelist pairing mode.

In the whitelist pairing mode it is possible to read an RFID token with the RFID reader or to get the MAC address of an EV supporting autocharge and to store it temporarily without adding it to the local whitelist. The temporary tag will remain until the pairing mode will be enabled again. The list will be cleared on power fail.

The pairing mode may only be enabled if the controller is in idle mode.

The pairing mode is active for 60 seconds or until a token is read successfully. When a token is read there will also be an acoustic feedback.

When a token is read in the pairing mode, it will be checked against the local whitelist. If it is already in the list, the buzzer will beep two times. If the tag is not in the list, the buzzer will beep one time and the tag will be readable then via the endpoint /v1/whitelist/pairing.

It is only possible to read one RFID token at once.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
success
required
boolean

Success of the operation, here true

Response samples

Content type
application/json
{
  • "success": true
}

[/v1/whitelist/pairing] Read the last scanned whitelist token in pairing mode

Full endpoint path: /v1/whitelist/pairing

Read the last scanned whitelist token in the whitelist pairing mode.

The supported tag types are RFID, EVCCID, and NFC.

If the id already exists, the response body will contain the known token data.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
id
required
string

The tag used to identify the local whitelist entry

tagType
string
Enum: "RFID" "EVCCID" "NFC"

The tag type (RFID, EVCCID, or NFC)

number
integer

An optional alias number for the 'id' tag, specified by the chargepoint user

name
string

An optional alias name for the 'id' tag, specified by the chargepoint user

userid
string <UUID>

A user id belonging to the local whitelist entry

priority
string
Enum: "NORMAL" "HIGH"

The priority of the local whitelist entry (normal/high)

Response samples

Content type
application/json
Example
{
  • "id": "abcdef12",
  • "tagType": "RFID"
}

Generic Key-Value Store

Generic key-value store (mappings between arbitrary unique keys and arbitrary values.) Contents stored in this database are specified by the customer and do not have any influence on the charge controller functionality.

[/v1/map] Get all key/value pairs from the database

Full endpoint path: /v1/map

Get all existing key/value pairs from the database.

The maximum number of key/value pairs in the database is limited to 1000.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
object (KeyValuePairs)

Multiple key/value pair(s) separated by commas

Response samples

Content type
application/json
{
  • "key_1": "value_1",
  • "key_2": "value_2",
  • "key_3": "value_3"
}

[/v1/map] Add new key/value pair(s) to database

Full endpoint path: /v1/map

Add new key/value pair(s) to the database. One or multiple key/value pair(s) may be added within the same request.

The maximum number of key/value pairs in the database is limited to 1000. Maximum key length is 256 characters and maximum value length is 1000 characters.

The database operations are carried out with sql start transaction & commit/rollback so that either the entire transaction will succeed or fail. It will fail if at least one of the keys already exists or if the number of keys in the database has exceeded the limit.

Authorizations:
sessionIdAuth
Request Body schema: application/json
required
object (KeyValuePairs)

Multiple key/value pair(s) separated by commas

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "cause": "too many entries"
}

[/v1/map] Modify existing key/value pair(s) in database

Full endpoint path: /v1/map

Modify the value(s) of existing key/value pair(s) in the database specified by their key(s). One or multiple key/value pair(s) may be modified within the same request.

Maximum value length is 1000 characters.

The database operations are carried out with sql start transaction & commit/rollback so that either the entire transaction will succeed or fail. It will fail if a key does not exist or if the new value length is too large.

Authorizations:
sessionIdAuth
Request Body schema: application/json
required
object (KeyValuePairs)

Multiple key/value pair(s) separated by commas

Responses

Response Schema: application/json
success
required
boolean

Success of the operation, here true

Response samples

Content type
application/json
{
  • "success": true
}

[/v1/map/{key}] Get one key/value pair from database

Full endpoint path: /v1/map/{key}

Get one existing key/value pair from the database specified by its key.

Authorizations:
sessionIdAuth
path Parameters
key
required
string
Example: key_1

The key of the key/value pair that needs to be retrieved

Responses

Response Schema: application/json
object (KeyValuePair)

One key/value pair

Response samples

Content type
application/json
{
  • "key_1": "value_1"
}

[/v1/map/{key}] Delete one key/value pair from database

Full endpoint path: /v1/map/{key}

Delete one existing key/value pair from the database specified by its key.

Authorizations:
sessionIdAuth
path Parameters
key
required
string
Example: key_1

The key of the key/value pair that needs to be deleted

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "cause": "key not found"
}

System State

Information on the charge controller system state

[/v1/system_state] Get system state infos

Full endpoint path: /v1/system_state

Get infos on the current system state of the charger at any given point of time.

If the charger has an active transaction ongoing, the available information on the running transaction will also be included.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
systemState
required
string
Enum: "idle" "connected" "wait_for_auth" "charging" "charging_pause" "finished" "unavailable" "error"

The system state

connectionState
required
string
Enum: "no_vehicle_connected" "vehicle_connected_schuko" "vehicle_charging_schuko" "vehicle_connected_type2" "vehicle_charging_type2" "vehicle_connector_error"

The connection state

authState
required
string
Enum: "not_authorized_for_charging" "wait_for_auth" "authorized_for_charging" "auth_timeout"

The authorization state

ocppState
required
string
Enum: "available" "occupied" "reserved" "unavailable" "faulted" "preparing" "charging" "suspendedevse" "suspendedev" "finishing"

The OCPP backend state

type2State
required
string
Enum: "a" "b" "c" "d" "e"

The type 2 state

ambientTemp
number

The ambient temperature in °C of the chargepoint

object (ActiveTransactionDetails)
transactionId
required
string <UUID>

The unique transaction identifier of the transaction

backendTransactionId
string

The unique transaction identifier of the transaction set by the backend

userId
string <UUID>

The user identifier associated with the transaction

transactionStart
required
string <UTC date-time>

The beginning timestamp of the transaction

transactionDuration
integer

The time in s since the beginning of the transaction

tagId
string

The tag identifier used for the transaction

consumption
required
integer

The energy in Wh consumed since the beginning of the transaction

power
required
integer

The current charging power in W of the transaction

maxPower
required
integer

The maximum charging power in W since the beginning of the transaction

object

The current in A measured at the OCPP meter. A single-phase system will only show L1. A three-phase system will show L1, L2, L3. If no value is available, L1 will be -1.

L1
required
number

The L1 current in A

L2
number

The L2 current in A (in case of a three-phase system)

L3
number

The L3 current in A (in case of a three-phase system)

Response samples

Content type
application/json
{
  • "systemState": "idle",
  • "connectionState": "vehicle_charging_type2",
  • "authState": "authorized_for_charging",
  • "ocppState": "charging",
  • "type2State": "c",
  • "ambientTemp": 23.4,
  • "transaction": {
    • "transactionId": "2r41855c-6492-67ea-898f-98uz8ce45tzu",
    • "backendTransactionId": "123456",
    • "userId": "abc1855c-abc2-67ea-898f-98uz8ce45abc",
    • "transactionStart": "2019-11-25T19:35:43.511Z",
    • "transactionDuration": 300,
    • "tagId": "0102b0a5fd",
    • "consumption": 2345,
    • "power": 12000,
    • "maxPower": 14000,
    • "OCPPMeterCurrent": {
      }
    }
}

Logging

Overview of charge controller log messages

[/v1/messages] Get error and warning messages

Full endpoint path: /v1/messages

Get all current error and warning messages of the charge controller.

Errors prevent the chargepoint from charging, warnings are informative.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
Array of objects (Message)
Array
severity
required
string
Enum: "ERROR" "WARNING"

The severity of the message (error/warning)

errorCode
required
string

The error/warning code

message
required
string

The human-readable error/warning message

correctiveActions
string

An optional hint on required actions

Response samples

Content type
application/json
{
  • "messages": {
    • "0": {
      },
    • "1": {
      }
    }
}

App Settings Parameters

[/v1/app_settings] Get the settings parameters for the App

Full endpoint path: /v1/app_settings

Get all respective settings parameters designated for the App.

Authorizations:
sessionIdAuth

Responses

Response Schema: application/json
name
required
string

Name of the response object, always 'settings'

required
object
reboot_required
required
boolean

States if the charge controller has to be rebooted due to a previously changed value

required
Array of objects (Group)

Array of groups of settings parameters

Array
role
string
Enum: "dev" "manufacturer" "operator" "user" "installer" "manufacturer+" "operator+" "user+" "installer+"

User access level of the group

The access level is related to the app user currently logged in. The lowest access level is 'installer', the highest access level is 'dev' (developer).

A '+' behind the role name includes all other roles having a higher access level.

key
required
string
Enum: "network" "backend" "authorization" "whitelists" "loadmanagement" "installation" "system" "devel"

Unique key name of the group

The key names are machine-readable identifiers of the groups.

label
required
string
Enum: "Network" "Backend" "Authorization" "Whitelists" "Load Management" "Installation" "System" "Development"

Label of the group

The labels are human-readable identifiers of the groups.

required
Array of objects (SubGroup)

Array of subgroups of settings parameters

required
object (ChargePointInfo)

Additional info on the chargepoint features

required
Array of objects

The translation languages offered by the chargepoint

Array
key
required
string
Enum: "gb" "de" "nl" "fr"

The key name of a language

value
required
integer

The enum value of a language

lang
required
string
Enum: "en_GB" "de_DE" "nl_NL" "fr_FR"

The ISO language code of a language

label
required
string
Enum: "English" "Deutsch" "Nederlands" "Français"

The name of a language

active
boolean

Marks the language currently active, i.e. selected by the app user.

MultipleConnectors
required
boolean

States if the chargepoint features more than one connector

ControllerHemX2
required
boolean

States if the charge controller hardware is a HEM-X2 variant

OCPPWLEnabled
required
boolean

States if the OCPP whitelist is enabled

FLLEnabled
required
boolean

States if the local whitelist is enabled

Response samples

Content type
application/json
{
  • "name": "settings",
  • "result": {
    • "reboot_required": false
    },
  • "groups": {
    • "0": {
      },
    • "1": {
      },
    • "2": "..."
    },
  • "ChargePointInfo": {
    • "languages": {
      },
    • "MultipleConnectors": false,
    • "ControllerHemX2": false,
    • "OCPPWLEnabled": true,
    • "FLLEnabled": true
    }
}

App Dashboard Parameters

[/v1/app_dashboard] Get the dashboard parameters for the App

Full endpoint path: /v1/app_dashboard

Get all respective dashboard parameters designated for the App.

Authorizations:
sessionIdAuth
query Parameters
descriptions
integer
Example: descriptions=descriptions=0

Receive the description for parameters in the results. Defaults to 1

Responses

Response Schema: application/json
name
required
string

Name of the response object, always 'dashboard'

settings_changed
required
boolean

Notifies whether settings have changed on the controller since the last time they were retrieved

ControllerTime_custom
required
string

Date and time in UTC of controller

Array of objects (Group)

Array of groups of dashboard parameters

Array
role
string
Enum: "dev" "manufacturer" "operator" "user" "installer" "manufacturer+" "operator+" "user+" "installer+"

User access level of the group

The access level is related to the app user currently logged in. The lowest access level is 'installer', the highest access level is 'dev' (developer).

A '+' behind the role name includes all other roles having a higher access level.

key
required
string
Enum: "network" "backend" "authorization" "whitelists" "loadmanagement" "installation" "system" "devel"

Unique key name of the group

The key names are machine-readable identifiers of the groups.

label
required
string
Enum: "Network" "Backend" "Authorization" "Whitelists" "Load Management" "Installation" "System" "Development"

Label of the group

The labels are human-readable identifiers of the groups.

required
Array of objects (SubGroup)

Array of subgroups of settings parameters

Array of objects (Field)

Array of parameters and values needed for the dashboard

Array
role
string
Enum: "dev" "manufacturer" "operator" "user" "installer" "manufacturer+" "operator+" "user+" "installer+"

User access level of the parameter

The access level is related to the app user currently logged in. The lowest access level is 'installer', the highest access level is 'dev' (developer).

A '+' behind the role name includes all other roles having a higher access level.

key
required
string

Unique key name of the parameter

required
string or object or integer or Array of integers

Value of the parameter, the format depends on the 'type'

type
required
string
Enum: "string" "enum" "int" "triple"

Type of the parameter, one of four options (string, enum, int, triple)

mode
required
string
Enum: "rw" "ro"

Access mode of the parameter (read and write, read-only)

object or object

Validation rules for the 'value', depends on the 'type' (available for 'string' and 'int' type, otherwise omitted)

required
string or object or integer or Array of integers

Default value of the parameter, the format depends on the 'type'

label
required
string

short description (one line) of the parameter

description
required
string

long description (text) of the parameter

Array of objects

Array of parent parameters belonging to the parameter

The parameter will only be shown if the given parent parameter(s) have/has one of the given values.

isNotAuthorized
integer

If set to 1, current user may not save this value and should be hidden. It is useful for parameters that have dependencies on it to hide/show.

see @parents but may not be modified by the current user.

logged_in
boolean

Whether or not the user is logged in

message
string

Localized explanation why retrieving the dashboard parameters failed

code
integer (SessionErrorCodes)
Enum: 0 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015

The error code reason for the failure

Dictionary of error codes:

  • 0 No Error
  • 1001 Invalid credentials
  • 1002 Not logged in
  • 1003 Wrong session id
  • 1004 Session timed out
  • 1005 IP doesn't match session IP
  • 1006 PUK not presented
  • 1007 Invalid JSON data
  • 1008 Bad data
  • 1009 Password change not allowed by this user
  • 1010 Internal error
  • 1011 Too much data in body
  • 1012 No data in body
  • 1013 Too many PUK fails
  • 1014 Wrong PUK
  • 1015 PUK validation rate limit exceeded

Response samples

Content type
application/json
{
  • "name": "dashboard",
  • "ControllerTime_custom": "2023-05-18 08:51",
  • "settings_changed": false,
  • "groups": {
    • "0": {
      },
    • "1": {
      },
    • "2": "..."
    },
  • "GraphicDashboard": {
    • "0": {
      },
    • "1": {
      },
    • "2": {
      },
    • "3": "..."
    }
}