Skip to main content
Version: 5.32

API Reference

API docs by Redocly

ebee Charge Controller REST API (v1.0)

Download OpenAPI specification:Download

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.

Get a (one-time) token to hash the login password

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 samples

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

Perform the login on the charge controller

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

Request samples

Content type
application/json
{
  • "username": "operator",
  • "password": "b8098f9af264d6e287cbe6ea5c3d16bc32277fdd43b50e1ed9b865"
}

Response samples

Content type
application/json
{
  • "logged_in": true,
  • "session": {
    }
}

Perform the logout from the charge controller

Perform the logout and terminate the user session.

Authorizations:
sessionIdAuth

Responses

Response samples

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

Settings Parameters

View and edit the settings parameters of the charge controller.

Get all or specific settings parameters

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

Request samples

Content type
application/json
{
  • "params": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "name": "settings",
  • "result": {
    },
  • "groups": [
    ],
  • "ChargePointInfo": {
    }
}

Set specific settings parameters

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

Request samples

Content type
application/json
{
  • "params": [
    ]
}

Response samples

Content type
application/json
{
  • "params": [
    ],
  • "reboot_required": true
}

Set specific settings parameters, including parameter validation

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

Request samples

Content type
application/json
{
  • "params": [
    ]
}

Response samples

Content type
application/json
{
  • "params": [
    ],
  • "reboot_required": true
}

Charging Transactions

Information on charging transactions

Get infos on completed charging transactions in detail

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 samples

Content type
application/json
[
  • {
    },
  • "..."
]

Get a summary of completed transactions

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 samples

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

Check if a transaction is running

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

Authorizations:
sessionIdAuth

Responses

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)

Get all users from the database

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 samples

Content type
application/json
{
  • "users": [
    ]
}

Add a new user to the database

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

Request samples

Content type
application/json
{
  • "userName": "Jenny"
}

Response samples

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

Get one existing chargepoint user from the database

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 samples

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

Modify one existing chargepoint user in the database

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

Request samples

Content type
application/json
{
  • "userName": "Alex1"
}

Response samples

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

Delete one existing chargepoint user from the database

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.

Get all whitelist entries

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 samples

Content type
application/json
{
  • "success": true,
  • "tags": [
    ]
}

Add or edit specific whitelist entries, or clear all whitelist entries

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

Request samples

Content type
application/json
Example
{
  • "type": "local",
  • "command": "add",
  • "tags": [
    ]
}

Response samples

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

Delete specific whitelist entries

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

Request samples

Content type
application/json
{
  • "type": "local",
  • "command": "delete",
  • "tags": [
    ]
}

Response samples

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

Enable the whitelist pairing mode

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 samples

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

Read the last scanned whitelist token in pairing mode

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 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.

Get all key/value pairs from the database

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 samples

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

Add new key/value pair(s) to database

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

Request samples

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

Response samples

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

Modify existing key/value pair(s) in database

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

Request samples

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

Response samples

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

Get one key/value pair from database

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 samples

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

Delete one key/value pair from database

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

Get system state infos

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 samples

Content type
application/json
{
  • "systemState": "idle",
  • "connectionState": "vehicle_charging_type2",
  • "authState": "authorized_for_charging",
  • "ocppState": "charging",
  • "type2State": "c",
  • "ambientTemp": 23.4,
  • "transaction": {
    }
}

Logging

Overview of charge controller log messages

Get error and warning 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 samples

Content type
application/json
{
  • "messages": [
    ]
}

App Settings Parameters

Get all settings parameters for the App

Get all settings parameters designated for the App.

Authorizations:
sessionIdAuth

Responses

Response samples

Content type
application/json
{
  • "name": "settings",
  • "result": {
    },
  • "groups": [
    ],
  • "ChargePointInfo": {
    }
}

App Dashboard Parameters

Get the dashboard parameters for the App

Get all dashboard parameters that are defined in app_layout.xml.

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

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

Responses

Response samples

Content type
application/json
{
  • "name": "dashboard",
  • "ControllerTime_custom": "2023-05-18 08:51",
  • "settings_changed": false,
  • "groups": [
    ],
  • "GraphicDashboard": [
    ]
}
Last updated on