Overview

VDV-261 API

The VDV-261 API facilitates an interface that allows the EV (Electric Vehicle) to communicate and send VDV-261 parameters to the DepotFinity backend. Software solutions serve as a uniform communication means between the EV and different backend systems. The communication between the EV and charging station is a part of the ISO standard 15118, Ed. 1 which is now an established standard.

Prerequisites

Complete the following prerequisite actions.

1. Enable preconditioning after onboarding an EV.
2. Enable secure connection to the EV and copy it's credentials.
3. Request for V2ICP root certificate and credentials from Siemens Regional Support.
4. Schedule the vehicle on smart charging group and confirm that the password is synchronized.
5. Execute the VDV-261 API with basic authentication and necessary body parameters.

API Usage

The VDV-261 API uses basic authentication method to authenticate the EV. DepotFinity uses the "VIN" (Vehicle Identification Number) as vin and password.

The following sample shows the format of the Authorization header.

const VIN = <YOUR_VIN>;
const PASSWORD = <YOUR_PASSWORD>;

// create a base64 encoded string with VIN and PASSWORD
const YOUR_VDV261_TOKEN = Base64Encoder("${VIN}:${PASSWORD}");

// add the authorization header
Authorization: Basic ${YOUR_VDV261_TOKEN}

Prepare Request Body

To prepare a request body, set the Content-Type header as application/json and use the parameters as described in VDV-261 API Reference.

Example Request

Note

Use the server URL applicable to your region. See [API Reference](./vdv261_api_reference.md) for available server URLs applicable to your region.

export VDV261_TOKEN = <YOUR_VDV261_TOKEN>

export SEQ = <YOUR_SEQ>,
export VIN = <YOUR_VIN>,
export EVCCID = <YOUR_EVCCID>
export ODO = <YOUR_ODO>
export BAT_REQTIME = <YOUR_BAT_REQTIME>
export BAT_EAMOUNT = <YOUR_BAT_EAMOUNT>
export BPREC_EAMOUNT = <YOUR_BPREC_EAMOUNT>
export PREC_REQTIME = <YOUR_PREC_REQTIME>
export PREC_EAMOUNT = <YOUR_PREC_EAMOUNT>
export CHRG_STAT = <YOUR_CHRG_STAT>

curl --location --request POST 'https://ev.eu.depot.emobility.io/vdv' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic $VDV261_TOKEN' \
  --data-raw '{
    "seq": "$SEQ",
    "vin": "$VIN",
    "evccid": "$EVCCID",
    "odo": $ODO,
    "bat_reqtime": $BAT_REQTIME,
    "bat_eamount": $BAT_EAMOUNT,
    "bprec_eamount": $BPREC_EAMOUNT,
    "prec_reqtime": $PREC_REQTIME,
    "prec_eamount": $PREC_EAMOUNT,
    "chrg_stat": $CHRG_STAT
  }'

Response Body

Successful response returns 200 HTTP status code with response body as TimeSeriesResponseBody schema. For more information, see VDV-261 API Reference.

Example Response

On the first request with VIN and other parameters, the response contains seq, driveoff, prec_dsrd, prec_hvac, ambienttemp, and vin parameters.

{
  "seq": 0,
  "driveoff": 409,
  "prec_dsrd": 1,
  "prec_hvac": 3,
  "ambienttemp": 255,
  "vin": "120"
}

On subsequent requests with the same parameters, the response contains only vin and seq parameters.

{
  "seq": 0,
  "vin": "120"
}