openapi: 3.0.3 info: title: ebee Charge Controller REST API description: >- **Note: All API endpoints are prefixed with `/v1`** ## 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. version: v1.0 externalDocs: description: OpenAPI 3.0 spec url: https://swagger.io/specification/v3/ servers: - url: http://192.168.123.123/v1 - url: http://127.0.0.1:8077/v1 security: - sessionIdAuth: [] tags: - name: App User Authentication description: >- Authenticate the app user when accessing the charge controller via app, start or terminate a user session. - name: Settings Parameters description: View and edit the settings parameters of the charge controller. - name: Charging Transactions description: Information on charging transactions - name: Chargepoint Users Identity description: >- Identity of chargepoint users and cars (mappings between user names and unique user ids) - name: Whitelisting description: >- Handle the (local) whitelist of chargepoint users and cars authorised for charging. Possible ids include RFID tags, EVCCIDs, and NFC. - name: Generic Key-Value Store description: >- 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. - name: System State description: Information on the charge controller system state - name: Logging description: Overview of charge controller log messages paths: /login: get: deprecated: false tags: - App User Authentication summary: '[/v1/login] Get a (one-time) token to hash the login password' description: | **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. operationId: getLoginToken responses: '200': description: OK (successfully got a new login token) content: application/json: schema: $ref: '#/components/schemas/LoginToken' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' security: [] x-displayPath: /v1/login post: deprecated: false tags: - App User Authentication summary: '[/v1/login] Perform the login on the charge controller' description: >- **Full endpoint path: `/v1/login`** Perform the actual login and start a user session. Each login attempt will need a new login token. operationId: performLogin requestBody: description: | 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. content: application/json: schema: $ref: '#/components/schemas/LoginCredentials' required: true responses: '200': description: > OK (successfully logged in, got a new valid session id) This session id needs to be set in the HTTP 'Authorization' header of all subsequent API calls during the same login session. Otherwise the response to such API calls will be '401 Unauthorized' and the 'NotLoggedIn' schema. content: application/json: schema: $ref: '#/components/schemas/LoginSucceeded' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadLoginRequest' '401': description: Unauthorized (invalid login credentials) content: application/json: schema: $ref: '#/components/schemas/InvalidLoginCredentials' security: [] x-displayPath: /v1/login /logout: post: tags: - App User Authentication summary: '[/v1/logout] Perform the logout from the charge controller' description: |- **Full endpoint path: `/v1/logout`** Perform the logout and terminate the user session. operationId: performLogout responses: '204': description: >- OK, No Content (successfully logged out, the session id is invalid now) '401': description: Unauthorized (not logged in at all) content: application/json: schema: $ref: '#/components/schemas/NotLoggedIn' x-displayPath: /v1/logout /settings: get: tags: - Settings Parameters summary: '[/v1/settings] Get all or specific settings parameters' description: > **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. operationId: getAllOrSpecificSettings parameters: - name: params in: query description: > 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) required: false explode: true schema: type: string example: Enabled_wlan,WebUIStyle_web,SysTime_mon requestBody: description: > 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) required: false content: application/json: schema: $ref: '#/components/schemas/GetSpecificSettingsParametersRequest' deprecated: true responses: '200': description: >- OK (successfully got all settings or specific settings of the charge controller) content: application/json: schema: oneOf: - $ref: '#/components/schemas/GetAllSettingsParametersResponse' - $ref: '#/components/schemas/GetSpecificSettingsParametersResponse' examples: allSettings: summary: all settings value: name: settings result: reboot_required: false groups: - role: user+ key: network label: Network sub_groups: - key: gsm label: GSM fields: - key: WebUIEnabledGSM_modem value: value: 1 label: Show type: enum mode: rw default: value: 0 label: Hide label: Show Modem Configuration description: Show or hide the modem configuration. - key: APN_modem value: Vodafone type: string mode: rw validation: length: - 0 - 100 default: '' label: Access Point Name (APN) description: >- Access Point Name of the mobile network to be used when establishing connections to the backend system via the built-in modem. parents: - name: WebUIEnabledGSM_modem value: - 1 - ... - key: lan label: LAN fields: - ... - ... - key: backend label: Backend sub_groups: - role: operator+ key: connection label: Connection fields: - key: Type_dl value: value: 1 label: GSM type: enum mode: rw default: value: 0 label: No Backend label: Connection Type description: >- The type of data connection used to connect to the backend system. Choose 'No Backend' to disable backend communication completely. While using GSM the wallbox can be connected to LAN/WLAN at the same time. - ... - key: ocpp label: OCPP fields: - ... - ... - ... ChargePointInfo: languages: - key: gb value: 0 lang: en_GB label: English active: true - key: de value: 1 lang: de_DE label: Deutsch - ... MultipleConnectors: false ControllerHemX2: false OCPPWLEnabled: true FLLEnabled: true specificSettings: summary: specific settings value: params: - Enabled_wlan: value: 0 label: 'Off' - WebUIStyle_web: value: 2 label: 2.0 only - SysTime_mon: 1645784010 '400': description: >- Bad Request (e.g. malformed request, or the URL query or the request payload is too large) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: unable to get key name '404': description: >- Not Found ('get specific settings' option - at least one key name of the specified parameters was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: key 'ForceStateAvail_' not found '500': description: Internal Server Error ('get all settings' option) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/settings post: tags: - Settings Parameters summary: '[/v1/settings] Set specific settings parameters' description: >- **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. operationId: setSpecificSettings requestBody: description: The key names and new values of the settings parameters to be set content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersRequest' required: true responses: '200': description: OK (successfully set specific settings of the charge controller) content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersResponseSucceeded' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersResponseFailed' x-displayPath: /v1/settings patch: tags: - Settings Parameters summary: >- [/v1/settings] Set specific settings parameters, including parameter validation description: > **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 operationId: validateAndSetSpecificSettings requestBody: description: >- The key names and new values of the settings parameters to be validated and set content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersRequest' required: true responses: '200': description: >- OK (successfully validated and set specific settings of the charge controller) content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersResponseSucceeded' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/SetSettingsParametersResponseFailed' x-displayPath: /v1/settings /transactions: get: tags: - Charging Transactions summary: >- [/v1/transactions] Get infos on completed charging transactions in detail description: > **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. operationId: getTransactionsDetails parameters: - name: from in: query description: The beginning of a specified timespan required: false explode: true schema: type: string format: UTC date-time example: '2019-11-23T19:35:43.511Z' - name: to in: query description: The end of a specified timespan required: false explode: true schema: type: string format: UTC date-time example: '2019-11-24T19:35:43.511Z' responses: '200': description: OK (successfully got the requested transactions) content: application/json: schema: type: array items: $ref: '#/components/schemas/CompletedTransactionDetails' example: - 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 - ... '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid date format for 'from' x-displayPath: /v1/transactions /transactions/summary: get: tags: - Charging Transactions summary: '[/v1/transactions/summary] Get a summary of completed transactions' description: > **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. operationId: getTransactionsSummary parameters: - name: from in: query description: The beginning of a specified timespan required: false explode: true schema: type: string format: UTC date-time example: '2019-11-23T19:35:43.511Z' - name: to in: query description: The end of a specified timespan required: false explode: true schema: type: string format: UTC date-time example: '2019-11-24T19:35:43.511Z' responses: '200': description: OK (successfully got the requested transactions summary) content: application/json: schema: $ref: '#/components/schemas/CompletedTransactionsSummary' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid date format for 'to' x-displayPath: /v1/transactions/summary /transactions/active: get: tags: - Charging Transactions summary: '[/v1/transactions/active] Check if a transaction is running' description: |- **Full endpoint path: `/v1/transactions/active`** Check if an active (incomplete) transaction is currently running. operationId: checkForActiveTransaction responses: '200': description: OK (an active transaction is currently running) content: application/json: schema: $ref: '#/components/schemas/OperationSucceeded' '204': description: OK, No Content (no active transaction is currently running) x-displayPath: /v1/transactions/active /users: get: tags: - Chargepoint Users Identity summary: '[/v1/users] Get all users from the database' description: >- **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. operationId: getAllUsers responses: '200': description: OK (successfully retrieved all users from the database) content: application/json: schema: $ref: '#/components/schemas/Users' example: users: - userId: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes userName: Alex - userId: 45d3711a-2acd-5812-cb44-f23fa3b791c2 userName: Jenny - ... '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/users post: tags: - Chargepoint Users Identity summary: '[/v1/users] Add a new user to the database' description: | **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. operationId: addUser requestBody: content: application/json: schema: type: object properties: userName: type: string description: The new user name example: Jenny required: true responses: '201': description: >- Created (successfully added the specified new user name to the database, the response contains the new associated user id) content: application/json: schema: $ref: '#/components/schemas/User' example: userId: 45d3711a-2acd-5812-cb44-f23fa3b791c2 userName: Jenny '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid payload x-displayPath: /v1/users /users/{userId}: get: tags: - Chargepoint Users Identity summary: '[/v1/users/{userId}] Get one existing chargepoint user from the database' description: >- **Full endpoint path: `/v1/users/{userId}`** Get one existing chargepoint user from the database specified by its user id. operationId: getUser parameters: - name: userId in: path description: The user id of the chargepoint user that needs to be retrieved required: true schema: type: string format: UUID example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes responses: '200': description: OK (successfully retrieved the specified user from the database) content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid path '404': description: Not Found (the specified user id was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: user not found x-displayPath: /v1/users/{userId} patch: tags: - Chargepoint Users Identity summary: >- [/v1/users/{userId}] Modify one existing chargepoint user in the database description: | **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. operationId: modifyUser parameters: - name: userId in: path description: The user id of the chargepoint user that needs to be modified required: true schema: type: string format: UUID example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes requestBody: content: application/json: schema: type: object properties: userName: type: string description: The changed user name example: Alex1 required: true responses: '200': description: OK (successfully modified the specified user in the database) content: application/json: schema: $ref: '#/components/schemas/OperationSucceeded' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid path '404': description: Not Found (the specified user id was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: user not found x-displayPath: /v1/users/{userId} delete: tags: - Chargepoint Users Identity summary: >- [/v1/users/{userId}] Delete one existing chargepoint user from the database description: >- **Full endpoint path: `/v1/users/{userId}`** Delete an existing chargepoint user from the database specified by its user id. operationId: deleteUser parameters: - name: userId in: path description: The user id of the chargepoint user that needs to be deleted required: true schema: type: string format: UUID example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes responses: '204': description: >- OK, No Content (successfully deleted the specified user from the database) '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid path '404': description: Not Found (the specified user id was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: user not found x-displayPath: /v1/users/{userId} /whitelist: get: tags: - Whitelisting summary: '[/v1/whitelist] Get all whitelist entries' description: |- **Full endpoint path: `/v1/whitelist`** Get all entries of the local whitelist. operationId: getWhitelistEntries parameters: - name: type in: query description: The whitelist type - only the 'local' whitelist is supported. required: true explode: true schema: type: string description: Whitelist type, always 'local' example: local responses: '200': description: OK (successfully got entries of the local whitelist) content: application/json: schema: type: object properties: success: type: boolean description: Success of the operation, here true example: true tags: type: array items: $ref: '#/components/schemas/WhitelistEntry' example: success: true tags: - id: abcdef12 tagType: RFID number: 12345 name: Alex userid: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes priority: NORMAL - ... '400': description: Bad Request (missing or unknown whitelist type) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid parameter 'type', valid value is 'local' x-displayPath: /v1/whitelist post: tags: - Whitelisting summary: >- [/v1/whitelist] Add or edit specific whitelist entries, or clear all whitelist entries description: | **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. operationId: addEditClearWhitelistEntries requestBody: content: application/json: schema: type: object properties: type: description: >- The whitelist type - only the 'local' whitelist is supported. type: string example: local command: type: string enum: - add - edit - clear example: add tags: type: array description: >- The whitelist entries that shall be added or edited (not needed in case of command 'clear') items: $ref: '#/components/schemas/WhitelistEntry' required: - type - command examples: addWhitelistEntry: summary: add an entry value: type: local command: add tags: - id: abcdef12 tagType: RFID number: 12345 name: Alex userid: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes priority: NORMAL editWhitelistEntry: summary: edit an entry value: type: local command: edit tags: - id: abcdef12 tagType: RFID number: 12345 name: Alex userid: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes priority: HIGH clearWhitelistEntries: summary: clear all entries value: type: local command: clear required: true responses: '200': description: >- OK (successfully added or edited the specified entries of the local whitelist, or cleared all entries) content: application/json: schema: $ref: '#/components/schemas/OperationSucceeded' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid value of parameter 'command' '404': description: >- Not Found (command 'edit' - at least one 'id' tag of the specified whitelist entries was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: failed to edit 1 tag(s) in local whitelist x-displayPath: /v1/whitelist delete: tags: - Whitelisting summary: '[/v1/whitelist] Delete specific whitelist entries' description: | **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.) operationId: deleteWhitelistEntries parameters: - name: type in: query description: The whitelist type - only the 'local' whitelist is supported. required: false explode: true schema: type: string description: Whitelist type, always 'local' example: local - name: ids in: query description: > 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. required: false explode: true schema: type: string example: abcdef12,abcdef34,abcdef56 requestBody: description: > Parameters to specify the desired whitelist entries that shall be deleted The request body should no longer be used, preferably use an URL query. required: false content: application/json: schema: $ref: '#/components/schemas/DeleteWhitelistEntriesRequest' deprecated: true responses: '204': description: >- OK, No Content (successfully deleted the specified entries of the local whitelist) '400': description: Bad Request (e.g. the URL query or the request payload is too large) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: missing parameter 'tags' '404': description: >- Not Found (at least one 'id' tag of the specified whitelist entries was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: failed to delete 2 tag(s) from local whitelist x-displayPath: /v1/whitelist /whitelist/pairing: post: tags: - Whitelisting summary: '[/v1/whitelist/pairing] Enable the whitelist pairing mode' description: > **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. operationId: enableWhitelistPairingMode responses: '200': description: OK (successfully enabled the whitelist pairing mode) content: application/json: schema: $ref: '#/components/schemas/OperationSucceeded' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/whitelist/pairing get: tags: - Whitelisting summary: >- [/v1/whitelist/pairing] Read the last scanned whitelist token in pairing mode description: > **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. operationId: getLastWhitelistToken responses: '200': description: OK (successfully got the last scanned token) content: application/json: schema: $ref: '#/components/schemas/WhitelistEntry' examples: newWhitelistToken: summary: new token value: id: abcdef12 tagType: RFID existingWhitelistToken: summary: existing token value: id: abcdef12 number: '12345' name: Alex userid: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes priority: HIGH tagType: RFID '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/whitelist/pairing /map: get: tags: - Generic Key-Value Store summary: '[/v1/map] Get all key/value pairs from the database' description: > **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. operationId: getAllKeyValuePairs responses: '200': description: OK (successfully fetched all key/value pairs from the database) content: application/json: schema: $ref: '#/components/schemas/KeyValuePairs' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/map post: tags: - Generic Key-Value Store summary: '[/v1/map] Add new key/value pair(s) to database' description: > **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. operationId: addKeyValuePairs requestBody: content: application/json: schema: $ref: '#/components/schemas/KeyValuePairs' required: true responses: '201': description: >- Created (successfully added the specified new key/value pair(s) to the database) '400': description: >- Bad Request (e.g. a new key or value length is too large, or the max number of keys is exceeded) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: too many entries '409': description: Conflict (at least one of the specified keys already exists) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: key already exists x-displayPath: /v1/map patch: tags: - Generic Key-Value Store summary: '[/v1/map] Modify existing key/value pair(s) in database' description: > **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. operationId: modifyKeyValuePairs requestBody: content: application/json: schema: $ref: '#/components/schemas/KeyValuePairs' required: true responses: '200': description: >- OK (successfully modified the specified key/value pair(s) in the database) content: application/json: schema: $ref: '#/components/schemas/OperationSucceeded' '400': description: Bad Request (e.g. a modified value length is too large) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: invalid payload '404': description: Not Found (at least one of the specified keys was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: key not found x-displayPath: /v1/map /map/{key}: get: tags: - Generic Key-Value Store summary: '[/v1/map/{key}] Get one key/value pair from database' description: |- **Full endpoint path: `/v1/map/{key}`** Get one existing key/value pair from the database specified by its key. operationId: getKeyValuePair parameters: - name: key in: path description: The key of the key/value pair that needs to be retrieved required: true schema: type: string example: key_1 responses: '200': description: >- OK (successfully retrieved the specified key/value pair from the database) content: application/json: schema: $ref: '#/components/schemas/KeyValuePair' '404': description: Not Found (the specified key was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: key not found x-displayPath: /v1/map/{key} delete: tags: - Generic Key-Value Store summary: '[/v1/map/{key}] Delete one key/value pair from database' description: >- **Full endpoint path: `/v1/map/{key}`** Delete one existing key/value pair from the database specified by its key. operationId: deleteKeyValuePair parameters: - name: key in: path description: The key of the key/value pair that needs to be deleted required: true schema: type: string example: key_1 responses: '204': description: >- OK, No Content (successfully deleted the specified key/value pair from the database) '404': description: Not Found (the specified key was not found) content: application/json: schema: $ref: '#/components/schemas/OperationFailed' example: success: false cause: key not found x-displayPath: /v1/map/{key} /system_state: get: tags: - System State summary: '[/v1/system_state] Get system state infos' description: > **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. operationId: getSystemState responses: '200': description: OK (successfully got system state infos) content: application/json: schema: $ref: '#/components/schemas/SystemState' example: 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: L1: 11.5 L2: 13.5 L3: 8.5 x-displayPath: /v1/system_state /messages: get: tags: - Logging summary: '[/v1/messages] Get error and warning messages' description: | **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. operationId: getAllMessages responses: '200': description: OK (successfully got all messages) content: application/json: schema: $ref: '#/components/schemas/Messages' example: messages: - severity: ERROR errorCode: powerMeterFailure message: OCPP meter not communicating - severity: WARNING errorCode: otherError message: Failed init - Metering, OCPP Logic, timezone correctiveActions: >- An inspection and maintenance is required for the chargepoint, issue probably has to be escalated to be handled by a support engineer. x-displayPath: /v1/messages /app_settings: get: tags: - App Settings Parameters summary: '[/v1/app_settings] Get the settings parameters for the App' description: | **Full endpoint path: `/v1/app_settings`** Get all respective settings parameters designated for the App. operationId: getAppSettingsParameters responses: '200': description: OK (successfully got all settings for the App) content: application/json: schema: $ref: '#/components/schemas/GetAllSettingsParametersResponse' example: name: settings result: reboot_required: false groups: - role: user+ key: network label: Network sub_groups: - key: gsm label: GSM fields: - key: WebUIEnabledGSM_modem value: value: 1 label: Show type: enum mode: rw default: value: 0 label: Hide label: Show Modem Configuration description: Show or hide the modem configuration. - key: APN_modem value: Vodafone type: string mode: rw validation: length: - 0 - 100 default: '' label: Access Point Name (APN) description: >- Access Point Name of the mobile network to be used when establishing connections to the backend system via the built-in modem. parents: - name: WebUIEnabledGSM_modem value: - 1 - ... - key: lan label: LAN fields: - ... - ... - key: backend label: Backend sub_groups: - role: operator+ key: connection label: Connection fields: - key: Type_dl value: value: 1 label: GSM type: enum mode: rw default: value: 0 label: No Backend label: Connection Type description: >- The type of data connection used to connect to the backend system. Choose 'No Backend' to disable backend communication completely. While using GSM the wallbox can be connected to LAN/WLAN at the same time. - ... - key: ocpp label: OCPP fields: - ... - ... - ... ChargePointInfo: languages: - key: gb value: 0 lang: en_GB label: English active: true - key: de value: 1 lang: de_DE label: Deutsch - ... MultipleConnectors: false ControllerHemX2: false OCPPWLEnabled: true FLLEnabled: true '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/app_settings /app_dashboard: get: tags: - App Dashboard Parameters summary: '[/v1/app_dashboard] Get the dashboard parameters for the App' description: | **Full endpoint path: `/v1/app_dashboard`** Get all respective dashboard parameters designated for the App. operationId: getAppDashboardParameters parameters: - name: descriptions in: query description: | Receive the description for parameters in the results. Defaults to 1 required: false explode: true schema: type: integer example: descriptions=0 responses: '200': description: OK (successfully got all dashboard parameters for the App) content: application/json: schema: $ref: '#/components/schemas/GetAllDashboardParametersResponse' example: name: dashboard ControllerTime_custom: 2023-05-18 08:51 settings_changed: false groups: - key: general label: General fields: - value: 0 type: int unit: sessions label: Total Charging Sessions mode: ro key: TransactionsInDatabase_sql - value: '0.0' type: string unit: minutes mode: ro label: Average duration per session key: AverageTransactionDurationStr_sql - value: '0.00' type: string unit: kWh mode: ro label: Average energy per session key: AveragekWh_sql - key: statistics label: Last month fields: - value: 0 type: int unit: sessions label: This month's transaction count mode: ro key: TransactionsThisMonth_sql - value: 0 type: int unit: kWh label: This month's kWh consumption mode: ro key: TotalkWhThisMonth_sql - ... GraphicDashboard: - key: EnergyInWhour_meter value: 'Total: 0 [Wh]' type: string mode: ro label: Energy isNotAuthorized: 1 - key: EnergyInWhour_meter_2 - key: DashboardErrorState_custom value: 0 type: int label: '' mode: ro isNotAuthorized: 1 - ... '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OperationFailed' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/OperationFailed' x-displayPath: /v1/app_dashboard components: schemas: OperationSucceeded: type: object properties: success: type: boolean description: Success of the operation, here true example: true required: - success OperationFailed: type: object properties: success: type: boolean description: Success of the operation, here false example: false cause: type: string description: The cause for the failed operation example: internal error required: - success - cause LoginToken: type: object properties: token: type: string description: >- Generated 32 characters random string, valid for one POST /login request example: '>2BGLs|@|TIYOi3@5kTvQRZg$xL- Response to all API calls (except for the */login* call) if not successfully logged in, or if no valid session id was included in the HTTP 'Authorization' header properties: logged_in: type: boolean description: The login status, here false example: false message: type: string description: The failure message example: Not logged in code: $ref: '#/components/schemas/SessionErrorCodes' required: - logged_in - message - code SessionErrorCodes: type: integer enum: - 0 - 1001 - 1002 - 1003 - 1004 - 1005 - 1006 - 1007 - 1008 - 1009 - 1010 - 1011 - 1012 - 1013 - 1014 - 1015 description: | 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 example: 1002 GetAllDashboardParametersResponse: type: object description: > The response object for the 'Get all dashboard parameters' call In case of success the response object will contain the respective dashboard data. If there was an error getting the dashboard parameters, the response object will contain the logged_in state, an error message, and an error code. properties: name: type: string description: Name of the response object, always 'dashboard' example: dashboard settings_changed: type: boolean description: >- Notifies whether settings have changed on the controller since the last time they were retrieved example: false ControllerTime_custom: type: string description: Date and time in UTC of controller example: 2023-06-01 21:04 UTC groups: type: array description: Array of groups of dashboard parameters items: $ref: '#/components/schemas/Group' GraphicDashboard: type: array description: Array of parameters and values needed for the dashboard items: $ref: '#/components/schemas/Field' logged_in: type: boolean description: Whether or not the user is logged in example: false message: type: string description: Localized explanation why retrieving the dashboard parameters failed example: Not logged in' code: $ref: '#/components/schemas/SessionErrorCodes' required: - name - ControllerTime_custom - settings_changed GetAllSettingsParametersResponse: type: object description: The response object for the 'get all settings parameters' call properties: name: type: string description: Name of the response object, always 'settings' example: settings result: type: object properties: reboot_required: type: boolean description: >- States if the charge controller has to be rebooted due to a previously changed value example: false required: - reboot_required groups: type: array description: Array of groups of settings parameters items: $ref: '#/components/schemas/Group' ChargePointInfo: $ref: '#/components/schemas/ChargePointInfo' required: - name - result - groups - ChargePointInfo GetSpecificSettingsParametersRequest: type: object description: The request object for the 'get specific settings parameters' call properties: params: type: array description: The parameter keys that shall be fetched items: type: string description: A single parameter key name example: Param_key example: - Enabled_wlan - WebUIStyle_web - SysTime_mon deprecated: true GetSpecificSettingsParametersResponse: type: object description: The response object for the 'get specific settings parameters' call properties: params: type: array description: The returned parameter key names and their current values items: type: object description: A single parameter key name and its current value example: Param_key: current_value example: - Enabled_wlan: value: 0 label: 'Off' - WebUIStyle_web: value: 2 label: 2.0 only - SysTime_mon: 1645784010 required: - params SetSettingsParametersRequest: type: object description: The request object for the 'set specific settings parameters' call properties: params: type: array description: The parameter key names and their new values that shall be set items: type: object description: A single parameter key name and its new value example: key: Param_key value: new_value example: - key: ForceStateAvail_ocpp value: 1 - key: WebUIStyle_web value: 2 required: - params SetSettingsParametersResponseSucceeded: type: object description: >- The response object for the 'set specific settings parameters' call (in case of success) properties: params: type: array description: The parameter key names and their setting success infos items: type: object description: A single parameter key name and its setting success info example: key: Param_key success: true example: - key: ForceStateAvail_ocpp success: true - key: WebUIStyle_web success: true reboot_required: type: boolean description: >- States if the charge controller has to be rebooted due to a changed value example: true required: - params - reboot_required SetSettingsParametersResponseFailed: type: object description: >- The response object for the 'set specific settings parameters' call (in case of failure) properties: params: type: array description: >- The parameter key names and their setting success infos and failure causes items: type: object description: >- A single parameter key name and its setting success info and failure cause example: key: Param_key success: false cause: parameter could not be set example: - key: ForceStateAv success: false cause: key 'ForceStateAv' not found - key: WebUIStyle_web success: false cause: not authorized reboot_required: type: boolean description: >- States if the charge controller has to be rebooted due to a changed value example: false required: - params - reboot_required Field: type: object description: A parameter field holding data of one parameter properties: role: type: string description: > 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. enum: - dev - manufacturer - operator - user - installer - manufacturer+ - operator+ - user+ - installer+ example: operator+ key: type: string description: Unique key name of the parameter example: EnableHTTPS_encryption value: description: Value of the parameter, the format depends on the 'type' oneOf: - type: string description: A string value example: ebee Smart Technologies GmbH - type: object description: An enum value properties: value: type: integer description: The enum value example: 1 label: type: string description: The human-readable label example: 'On' example: value: 1 label: 'On' - type: integer description: An integer value example: 10 - type: array description: | A triple value, consisting of three integer values (used for three-phase parameters like current, voltage, power) items: type: integer example: - 6 - 6 - 6 type: type: string description: >- Type of the parameter, one of four options (string, enum, int, triple) enum: - string - enum - int - triple example: triple mode: type: string description: Access mode of the parameter (read and write, read-only) enum: - rw - ro example: rw validation: description: >- Validation rules for the 'value', depends on the 'type' (available for 'string' and 'int' type, otherwise omitted) oneOf: - type: object description: >- Validator for a 'string' type value, indicating min and max length of the string properties: length: type: array items: type: integer example: length: - 0 - 15 - type: object description: >- Validator for an 'int' type value, indicating min and max value of the integer properties: range: type: array items: type: integer example: range: - 6 - 80 default: description: Default value of the parameter, the format depends on the 'type' oneOf: - type: string description: A string default value example: Bender GmbH & Co. KG - type: object description: An enum default value properties: value: type: integer description: The enum default value example: 0 label: type: string description: The human-readable label example: 'Off' example: value: 0 label: 'Off' - type: integer description: An integer default value example: 42 - type: array description: A triple default value, consisting of three integer values items: type: integer example: - 16 - 16 - 16 label: type: string description: short description (one line) of the parameter example: Enable HTTPS description: type: string description: long description (text) of the parameter example: >- Enable secure network communication between charge point and web browser. If the initial self-signed certificate is used, you need to add a security exception if the browser asks for it. parents: type: array description: | 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. example: - name: WebUIEnabledLAN_tcpip value: - 1 - name: NetworkConfig_mode_tcpip value: - 0 - 1 items: type: object description: A parent parameter, being a parent to a different parameter properties: name: type: string description: Unique key name of the parent parameter value: type: array description: >- Array of given values of a parent parameter, the format of each value depends on its type (string/enum/integer/triple value) items: oneOf: - type: string description: A string value - type: integer description: An enum value, only its integer value is given - type: integer description: An integer value - type: array description: A triple value, consisting of three integer values items: type: integer example: name: TCP_IP_MODE_V2_tcpip value: - 0 - 1 isNotAuthorized: type: integer description: > 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. required: - key - value - type - mode - default - label - description SubGroup: type: object description: A subgroup of settings parameters consisting of several parameter fields properties: role: type: string description: > User access level of the subgroup 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. enum: - dev - manufacturer - operator - user - installer - manufacturer+ - operator+ - user+ - installer+ example: operator+ key: type: string description: > Unique key name of the subgroup The key names are machine-readable identifiers of the subgroups. These key names depend on the related group, only few examples are given here. enum: - gsm - lan - usb - wlan - wifi_hotspot - ntp - ... example: gsm label: type: string description: > Label of the subgroup The labels are human-readable identifiers of the subgroups. These labels depend on the related group, only few examples are given here. enum: - GSM - LAN - USB - WLAN - WiFi Configuration Hotspot - NTP - ... example: GSM fields: type: array description: Array of parameter fields items: $ref: '#/components/schemas/Field' required: - key - label - fields Group: type: object description: A group of settings parameters consisting of several subgroups properties: role: type: string description: > 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. enum: - dev - manufacturer - operator - user - installer - manufacturer+ - operator+ - user+ - installer+ example: operator+ key: type: string description: | Unique key name of the group The key names are machine-readable identifiers of the groups. enum: - network - backend - authorization - whitelists - loadmanagement - installation - system - devel example: backend label: type: string description: | Label of the group The labels are human-readable identifiers of the groups. enum: - Network - Backend - Authorization - Whitelists - Load Management - Installation - System - Development example: Backend sub_groups: type: array description: Array of subgroups of settings parameters items: $ref: '#/components/schemas/SubGroup' required: - key - label - sub_groups ChargePointInfo: type: object description: Additional info on the chargepoint features properties: languages: type: array description: The translation languages offered by the chargepoint items: type: object properties: key: type: string description: The key name of a language enum: - gb - de - nl - fr example: gb value: type: integer description: The enum value of a language example: 0 lang: type: string description: The ISO language code of a language enum: - en_GB - de_DE - nl_NL - fr_FR example: en_GB label: type: string description: The name of a language enum: - English - Deutsch - Nederlands - Français example: English active: type: boolean description: >- Marks the language currently active, i.e. selected by the app user. example: true required: - key - value - lang - label MultipleConnectors: type: boolean description: States if the chargepoint features more than one connector example: false ControllerHemX2: type: boolean description: States if the charge controller hardware is a HEM-X2 variant example: false OCPPWLEnabled: type: boolean description: States if the OCPP whitelist is enabled example: true FLLEnabled: type: boolean description: States if the local whitelist is enabled example: true required: - languages - MultipleConnectors - ControllerHemX2 - OCPPWLEnabled - FLLEnabled WhitelistEntry: type: object properties: id: type: string description: The tag used to identify the local whitelist entry example: abcdef12 tagType: type: string description: The tag type (RFID, EVCCID, or NFC) enum: - RFID - EVCCID - NFC example: RFID number: type: integer description: >- An optional alias number for the 'id' tag, specified by the chargepoint user example: 12345 name: type: string description: >- An optional alias name for the 'id' tag, specified by the chargepoint user example: Alex userid: type: string description: A user id belonging to the local whitelist entry format: UUID example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes priority: type: string description: The priority of the local whitelist entry (normal/high) enum: - NORMAL - HIGH example: NORMAL required: - id WhitelistTag: type: object properties: id: type: string description: The tag used to identify the local whitelist entry example: abcdef12 required: - id DeleteWhitelistEntriesRequest: type: object description: The request object for the 'delete whitelist entries' call properties: type: description: The whitelist type - only the 'local' whitelist is supported. type: string example: local command: type: string description: The command, always 'delete' example: delete tags: type: array description: The 'id' tag(s) that shall be deleted items: $ref: '#/components/schemas/WhitelistTag' required: - type - command - tags deprecated: true CompletedTransactionDetails: type: object properties: transactionId: type: string format: UUID description: The unique transaction identifier of the transaction example: 4cd1855c-4492-67ea-898f-98uz8ce881qw backendTransactionId: type: string description: >- The unique transaction identifier of the transaction set by the backend example: '123456' tagId: type: string description: The tag identifier used for the transaction example: 0102b0a5fd userId: type: string format: UUID description: The user identifier associated with the transaction example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes startTransaction: type: string format: UTC date-time description: The beginning timestamp of the transaction example: '2019-11-23T19:35:43.511Z' endTransaction: type: string format: UTC date-time description: The end timestamp of the transaction example: '2019-11-24T19:35:43.511Z' consumption: type: integer description: The energy in Wh consumed during the transaction example: 2935 maxPower: type: integer description: The maximum charging power in W during the transaction example: 11000 required: - transactionId - startTransaction - endTransaction - consumption - maxPower CompletedTransactionsSummary: type: object properties: transactionCount: type: integer description: The number of completed transactions example: 12 totalDuration: type: integer description: The total duration in s of the transactions example: 2375 totalConsumption: type: integer description: The total energy in Wh consumed during the transactions example: 148 required: - transactionCount - totalDuration - totalConsumption ActiveTransactionDetails: type: object properties: transactionId: type: string format: UUID description: The unique transaction identifier of the transaction example: 2r41855c-6492-67ea-898f-98uz8ce45tzu backendTransactionId: type: string description: >- The unique transaction identifier of the transaction set by the backend example: '123456' userId: type: string format: UUID description: The user identifier associated with the transaction example: abc1855c-abc2-67ea-898f-98uz8ce45abc transactionStart: type: string format: UTC date-time description: The beginning timestamp of the transaction example: '2019-11-25T19:35:43.511Z' transactionDuration: type: integer description: The time in s since the beginning of the transaction example: 300 tagId: type: string description: The tag identifier used for the transaction example: 0102b0a5fd consumption: type: integer description: The energy in Wh consumed since the beginning of the transaction example: 2345 power: type: integer description: The current charging power in W of the transaction example: 12000 maxPower: type: integer description: >- The maximum charging power in W since the beginning of the transaction example: 14000 OCPPMeterCurrent: type: object description: >- 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. properties: L1: type: number description: The L1 current in A example: 11.5 L2: type: number description: The L2 current in A (in case of a three-phase system) example: 13.5 L3: type: number description: The L3 current in A (in case of a three-phase system) example: 8.5 required: - L1 required: - transactionId - transactionStart - consumption - power - maxPower KeyValuePair: type: object description: One key/value pair example: key_1: value_1 KeyValuePairs: type: object description: Multiple key/value pair(s) separated by commas example: key_1: value_1 key_2: value_2 key_3: value_3 User: type: object description: One chargepoint user properties: userId: type: string format: UUID description: The unique user identifier example: c9228f30-daa2-4a24-b9c0-e38aa2dc3fes userName: type: string description: The user name example: Alex required: - userId - userName Users: type: object description: Multiple chargepoint user(s) properties: users: type: array items: $ref: '#/components/schemas/User' SystemState: type: object properties: systemState: type: string description: The system state enum: - idle - connected - wait_for_auth - charging - charging_pause - finished - unavailable - error example: idle connectionState: type: string description: The connection state enum: - no_vehicle_connected - vehicle_connected_schuko - vehicle_charging_schuko - vehicle_connected_type2 - vehicle_charging_type2 - vehicle_connector_error example: vehicle_charging_type2 authState: type: string description: The authorization state enum: - not_authorized_for_charging - wait_for_auth - authorized_for_charging - auth_timeout example: authorized_for_charging ocppState: type: string description: The OCPP backend state enum: - available - occupied - reserved - unavailable - faulted - preparing - charging - suspendedevse - suspendedev - finishing example: charging type2State: type: string description: The type 2 state enum: - a - b - c - d - e example: c ambientTemp: type: number description: The ambient temperature in °C of the chargepoint example: 23.4 transaction: $ref: '#/components/schemas/ActiveTransactionDetails' description: >- detailed infos on the ongoing transaction, only present if there is a running transaction required: - systemState - connectionState - authState - ocppState - type2State Message: type: object description: One error or warning message properties: severity: type: string description: The severity of the message (error/warning) enum: - ERROR - WARNING example: ERROR errorCode: type: string description: The error/warning code example: powerMeterFailure message: type: string description: The human-readable error/warning message example: OCPP meter not communicating correctiveActions: type: string description: An optional hint on required actions example: An inspection and maintenance is required for the chargepoint. required: - severity - errorCode - message Messages: type: object description: Multiple error and warning messages properties: messages: type: array items: $ref: '#/components/schemas/Message' securitySchemes: sessionIdAuth: type: apiKey description: > The session id from the response of a successful POST */login* call needs to be set in the HTTP 'Authorization' header of all subsequent API calls during the same login session. Otherwise the response to such API calls will be '401 Unauthorized' and the 'NotLoggedIn' schema. name: Authorization in: header