openapi: 3.0.3
info:
  title: ebee Charge Controller REST API
  description: >-
    ## 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:
      tags:
        - App User Authentication
      summary: Get a (one-time) token to hash the login password
      description: |
        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: []
    post:
      tags:
        - App User Authentication
      summary: Perform the login on the charge controller
      description: >-
        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: []
  /logout:
    post:
      tags:
        - App User Authentication
      summary: Perform the logout from the charge controller
      description: 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'
  /settings:
    get:
      tags:
        - Settings Parameters
      summary: Get all or specific settings parameters
      description: >
        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/GetSpecificParametersRequest'
              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/GetAllParametersResponse'
                  - $ref: '#/components/schemas/GetSpecificParametersResponse'
              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'
    post:
      tags:
        - Settings Parameters
      summary: Set specific settings parameters
      description: >-
        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/SetParametersRequest'
        required: true
      responses:
        '200':
          description: OK (successfully set specific settings of the charge controller)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetParametersResponseSucceeded'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetParametersResponseFailed'
    patch:
      tags:
        - Settings Parameters
      summary: Set specific settings parameters, including parameter validation
      description: >
        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/SetParametersRequest'
        required: true
      responses:
        '200':
          description: >-
            OK (successfully validated and set specific settings of the charge
            controller)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetParametersResponseSucceeded'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetParametersResponseFailed'
  /transactions:
    get:
      tags:
        - Charging Transactions
      summary: Get infos on completed charging transactions in detail
      description: >
        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'
  /transactions/summary:
    get:
      tags:
        - Charging Transactions
      summary: Get a summary of completed transactions
      description: >
        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'
  /transactions/active:
    get:
      tags:
        - Charging Transactions
      summary: Check if a transaction is running
      description: 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)
  /users:
    get:
      tags:
        - Chargepoint Users Identity
      summary: Get all users from the database
      description: >-
        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'
    post:
      tags:
        - Chargepoint Users Identity
      summary: Add a new user to the database
      description: |
        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
  /users/{userId}:
    get:
      tags:
        - Chargepoint Users Identity
      summary: Get one existing chargepoint user from the database
      description: >-
        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
    patch:
      tags:
        - Chargepoint Users Identity
      summary: Modify one existing chargepoint user in the database
      description: |
        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
    delete:
      tags:
        - Chargepoint Users Identity
      summary: Delete one existing chargepoint user from the database
      description: >-
        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
  /whitelist:
    get:
      tags:
        - Whitelisting
      summary: Get all whitelist entries
      description: 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'
    post:
      tags:
        - Whitelisting
      summary: Add or edit specific whitelist entries, or clear all whitelist entries
      description: |
        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
    delete:
      tags:
        - Whitelisting
      summary: Delete specific whitelist entries
      description: |
        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
  /whitelist/pairing:
    post:
      tags:
        - Whitelisting
      summary: Enable the whitelist pairing mode
      description: >
        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'
    get:
      tags:
        - Whitelisting
      summary: Read the last scanned whitelist token in pairing mode
      description: >
        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'
  /map:
    get:
      tags:
        - Generic Key-Value Store
      summary: Get all key/value pairs from the database
      description: >
        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'
    post:
      tags:
        - Generic Key-Value Store
      summary: Add new key/value pair(s) to database
      description: >
        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
    patch:
      tags:
        - Generic Key-Value Store
      summary: Modify existing key/value pair(s) in database
      description: >
        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
  /map/{key}:
    get:
      tags:
        - Generic Key-Value Store
      summary: Get one key/value pair from database
      description: 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
    delete:
      tags:
        - Generic Key-Value Store
      summary: Delete one key/value pair from database
      description: >-
        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
  /system_state:
    get:
      tags:
        - System State
      summary: Get system state infos
      description: >
        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
  /messages:
    get:
      tags:
        - Logging
      summary: Get error and warning messages
      description: |
        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.
  /app_settings:
    get:
      tags:
        - App Settings Parameters
      summary: Get all settings parameters for the App
      description: Get all settings parameters designated for the App.
      operationId: getAllSettings
      responses:
        '200':
          description: OK (successfully got all settings for the App)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllParametersResponse'
              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'
  /app_dashboard:
    get:
      tags:
        - App Dashboard Parameters
      summary: Get the dashboard parameters for the App
      description: |
        Get all dashboard parameters that are defined in app_layout.xml.
      operationId: getAllDashboardParameters
      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'
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<rh3V'
      required:
        - token
    LoginCredentials:
      type: object
      properties:
        username:
          type: string
          description: The plain username
          example: operator
        password:
          type: string
          format: SHA-256 hash
          description: |
            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()
          example: b8098f9af264d6e287cbe6ea5c3d16bc32277fdd43b50e1ed9b865
      required:
        - username
        - password
    SessionId:
      type: string
      format: UUID
      description: The returned session id for the running user session
      example: cdc630cd-5e5f-4587-8a1a-a2e83ae990b5
    LoginSucceeded:
      type: object
      description: Login attempt succeeded due to valid login credentials
      properties:
        logged_in:
          type: boolean
          description: Login status, here true
          example: true
        session:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/SessionId'
          required:
            - id
      required:
        - logged_in
        - session
    InvalidLoginCredentials:
      type: object
      description: Login attempt failed due to invalid login credentials
      properties:
        logged_in:
          type: boolean
          description: Login status, here false
          example: false
        message:
          type: string
          description: The failure message
          example: Login failed - Invalid login credentials!
      required:
        - logged_in
        - message
    BadLoginRequest:
      type: object
      description: Login attempt failed due to bad request data
      properties:
        logged_in:
          type: boolean
          description: Login status, here false
          example: false
        message:
          type: string
          description: The failure message
          example: Login failed - Request data error!
      required:
        - logged_in
        - message
    NotLoggedIn:
      type: object
      description: >-
        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: Login status, here false
          example: false
        message:
          type: string
          description: The status message
          example: Not logged in
      required:
        - logged_in
        - message
    GetAllDashboardParametersResponse:
      type: object
      description: The response object for the 'Get all dashboard parameters' call
      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'
      required:
        - name
        - ControllerTime_custom
        - settings_changed
    GetAllParametersResponse:
      type: object
      description: The response object for the 'get all settings' 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
    GetSpecificParametersRequest:
      type: object
      description: The request object for the 'get specific settings' 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
    GetSpecificParametersResponse:
      type: object
      description: The response object for the 'get specific settings' 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
    SetParametersRequest:
      type: object
      description: The request object for the 'set specific settings' 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
    SetParametersResponseSucceeded:
      type: object
      description: >-
        The response object for the 'set specific settings' 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
    SetParametersResponseFailed:
      type: object
      description: >-
        The response object for the 'set specific settings' 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
