Changelog
HomeFAQSupportSDK
Back to All

Smart Charging Api v2.0

3 months ago by Sven Derksen

General Changes

We have added a newer version of the Smart Charging Api. To prevent issues & confusion, we have also added v2 to the other api's (Test Car & Virtual Power Plant). They don't contain any changes other then the version change in the route. The version 1 of these api's will become deprecated once we release a version with breaking changes. So v1 of those api's is not deprecated, and will not be removed soon. Version 1 of the Smart Charging Api will be marked as deprecated after we move out of the beta phase and will be removed in 6 months.

Paging

In places where we thought it would be useful, we added paging. They all follow the same pattern. You use the query parameters pageSize and pageIndex to determine the size of your pages & what page you are on. The page size is in limited to 100 items. Items are ordered from new to old. So for example GET /api/v2/charging-locations?pageSize=10&pageIndex=1 will return the the 10 newest charging locations. As in the example below.

{  
  "pageIndex": 1,  
  "pageSize": 100,  
  "totalPages": 1,  
  "totalCount": 1,  
  "items": [  
    {  
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
      "coordinates": {  
        "latitude": 0,  
        "longitude": 0  
      },  
      "address": {  
        "street": "string",  
        "postalCode": "string",  
        "houseNumber": "1A",  
        "city": "string",  
        "region": "string",  
        "country": "NL",  
        "area": "string"  
      },  
      "createdAt": "2023-12-19T13:26:55.109Z",  
      "updatedAt": "2023-12-19T13:26:55.109Z"  
    }  
  ]  
}

Dates & times

We have updated the dateformat for all responses returning a datetime. Before there would be all kinds of formats. We have update them to use a single format: yyyy-MM-ddTHH:mm:ss.fffZ e.g. 2023-10-31T09:20:46.123Z

We have also adjusted the query parameters of times. For example in GET /api/v2/sessions the startTimeFrom and other time related parameters use the same more readable format.

Enums and responses

To allow for additions & improvements without breaking the api contract, we are making some changes the the enums on responses. We are changing them to strings. They will still have the same options in the responses, but it should allow us to add additional values without breaking the contract.
Please be aware of this when adjusting your code for version 2. Your current code will probably still work, but once we add another option, it could mean that the response cannot be parsed anymore.

What's New

PUT /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

Replacing PUT /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

POST /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

Replacing POST /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

DELETE /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

Replacing DELETE /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

GET /users/{userId}/messages

List messages for a user in pages

What's Deleted

PUT /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

Replaced by PUT /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

POST /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

Replaced by POST /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

DELETE /users/{userId}/charging-locations/{chargingLocationId}/energy-supplier

Replaced by DELETE /users/{userId}/charging-locations/{chargingLocationId}/utility-contracts

POST /users/{userId}/charging-locations/{chargingLocationId}/chargers/start-connect-session

Connect a charger

GET /users/{userId}/messages/active

List active messages for a user
Use GET /users/{userId}/messages?includeDismissed=false for the same behavior. Endpoint now uses paging.

POST /users/{userId}/vehicles/{vehicleId}/session-settings

Update the settings for an active session by vehicleId
You can use the /users/{userId}/sessions/{sessionId}/session-settings instead, since they are related to a session, not a vehicle.

GET /users/{userId}/vehicles/{vehicleId}/session-settings/active

Retrieve the settings for an active session by vehicleId
You can use the /users/{userId}/sessions/{sessionId}/session-settings/active instead, since they are related to a session, not a vehicle.

POST /users/{userId}/vehicles/start-connect-session

Select and connect a vehicle

What's Changed

GET /charging-locations

List all charging locations of a tenant in pages

Parameters:

Added: createdFrom in query

Added: createdTo in query

Added: pageSize in query

Added: pageIndex in query

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json
    • Changed from array to object with an array of charging-locations in the items property.

GET /vehicles

List all vehicles of a tenant in pages

Parameters:

Added: createdFrom in query

Added: createdTo in query

Added: pageSize in query

Added: pageIndex in query

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed from array to object with an array of vehicles in the items property.

      • Changed property capabilities (array)

        Changed items (string):

        Removed enum values:

        • chargeState
        • stateOfCharge
        • charge
        • startStopDischarging
        • geoLocation
        • desiredStateOfCharge
        • pairing
        • departureTimes
        • pullTelemetry
        • pushTelemetry
        • geoFencing
        • startStopCharging

GET /sessions

List all sessions of a tenant in pages

Parameters:

Added: pageSize in query

The amount of entities returned in the list. Optional parameter, defaults to 20.

Added: pageIndex in query

The page that should be loaded. Optional parameter, defaults to 1

Changed: startTimeFrom in query

Beginning of date/time range for session start in UTC in date-time iso 8601 format.

Changed: startTimeTo in query

End of date/time range for session start in UTC in date-time iso 8601 format.

Changed: endTimeFrom in query

Beginning of date/time range for session end in UTC in date-time iso 8601 format.

Changed: endTimeTo in query

End of date/time range for session end in UTC in date-time iso 8601 format.

Return Type:

Changed response : 200 OK

Success

  • Changed from array to object with an array of sessions in the items property.

    • Changes to session object

      • Changed property status (string)

        The status of the session. Possible values: Active, Complete, ForceEnded

        Removed enum values:

        • unknown
        • active
        • complete
        • forceEnded
        • Changed property calibrationState (string)

          The calibration state of the session. Has value only for active session. Possible values: NoSession, NotStarted, InProgress, Complete

GET /supported-car-models

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property capabilities (array)

      Changed items (string):

      Removed enum values:

      • chargeState
      • stateOfCharge
      • charge
      • startStopDischarging
      • geoLocation
      • desiredStateOfCharge
      • pairing
      • departureTimes
      • pullTelemetry
      • pushTelemetry
      • geoFencing
      • startStopCharging

GET /users/{userId}/chargers

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property chargerState (object)

      State of the charger

      • Changed property chargeState (string)

        The charge state of the charger at the indicated time. Possible values: Complete, Charging, Disconnected, Stopped

        Removed enum values:

        • unknown
        • complete
        • charging
        • disconnected
        • stopped

GET /users/{userId}/charging-locations/{chargingLocationId}/chargers

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property chargerState (object)

      State of the charger

      • Changed property chargeState (string)

        The charge state of the charger at the indicated time. Possible values: Complete, Charging, Disconnected, Stopped

        Removed enum values:

        • unknown
        • complete
        • charging
        • disconnected
        • stopped

GET /users/{userId}/charging-locations/{chargingLocationId}/chargers/{chargerId}

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property chargerState (object)

      State of the charger

      • Changed property chargeState (string)

        The charge state of the charger at the indicated time. Possible values: Complete, Charging, Disconnected, Stopped

        Removed enum values:

        • unknown
        • complete
        • charging
        • disconnected
        • stopped

GET /users/{userId}/charging-locations/{chargingLocationId}/chargers/{chargerId}/state

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property chargeState (string)

      The charge state of the charger at the indicated time. Possible values: Complete, Charging, Disconnected, Stopped

      Removed enum values:

      • unknown
      • complete
      • charging
      • disconnected
      • stopped

GET /users/{userId}/charging-locations/{chargingLocationId}/dynamic-tariffs

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property dataType (string)

      Type of data. Values are: Actual, Forecast

      Removed enum values:

      • actual
      • forecast

GET /users/{userId}/charging-locations/{chargingLocationId}/solar-energy

Parameters:

Changed: startTime in query

Time the interval started in UTC in date-time iso 8601 format.

Changed: endTime in query

Time the interval finished in UTC in date-time iso 8601 format.

GET /users/{userId}/financials

Parameters:

Changed: startTimeFrom in query

Beginning of date/time range for session startin UTC in date-time iso 8601 format.

Changed: startTimeTo in query

End of date/time range for session start in UTC in date-time iso 8601 format.

Changed: endTimeFrom in query

Beginning of date/time range for session end in UTC in date-time iso 8601 format.

Changed: endTimeTo in query

End of date/time range for session end in UTC in date-time iso 8601 format.

GET /users/{userId}/messages/{messageId}

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property type (string)

      The message Type

      Removed enum values:

      • startSession
      • endSession
      • invalidCredentials
      • carNotFound
      • carNotReachable
      • zeInteractiveToBeActivated
      • zeInteractiveCannotBeActivated
      • zeInteractiveExpiresSoon
      • readyForPairing
      • sessionImpossible
      • checkCarActivation
      • receivedNoPower
      • geoLocationDisabled
      • audiNotPaired
      • audiPairingNotComplete
      • invalidUtilityContract
      • reconnectUtilityContract
      • invalidCredentialsBanner
      • myRenaultAccessRevoked
      • audiRemoteAccessDisabled
      • audiRemoteAccessDisabledBanner

    • Changed property notificationType (string)

      The type of the notification. Possible values: PushNotification, Email, SMS, Banner

      Removed enum values:

      • pushNotification
      • email
      • sms
      • banner

PATCH /users/{userId}/messages/{messageId}

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property type (string)

      The message Type

      Removed enum values:

      • startSession
      • endSession
      • invalidCredentials
      • carNotFound
      • carNotReachable
      • zeInteractiveToBeActivated
      • zeInteractiveCannotBeActivated
      • zeInteractiveExpiresSoon
      • readyForPairing
      • sessionImpossible
      • checkCarActivation
      • receivedNoPower
      • geoLocationDisabled
      • audiNotPaired
      • audiPairingNotComplete
      • invalidUtilityContract
      • reconnectUtilityContract
      • invalidCredentialsBanner
      • myRenaultAccessRevoked
      • audiRemoteAccessDisabled
      • audiRemoteAccessDisabledBanner

    • Changed property notificationType (string)

      The type of the notification. Possible values: PushNotification, Email, SMS, Banner

      Removed enum values:

      • pushNotification
      • email
      • sms
      • banner

GET /users/{userId}/sessions

List all sessions of a user in pages

Parameters:

Added: pageSize in query

The amount of entities returned in the list. Optional parameter, defaults to 20.

Added: pageIndex in query

The page that should be loaded. Optional parameter, defaults to 1

Changed: startTimeFrom in query

Beginning of date/time range for session start in UTC in date-time iso 8601 format.

Changed: startTimeTo in query

End of date/time range for session start in UTC in date-time iso 8601 format.

Changed: endTimeFrom in query

Beginning of date/time range for session end in UTC in date-time iso 8601 format.

Changed: endTimeTo in query

End of date/time range for session end in UTC in date-time iso 8601 format.

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json
    Changed from array to object with an array of sessions in the items property.

    • Changes to session object

      • Changed property status (string)

        The status of the session. Possible values: Active, Complete, ForceEnded

        Removed enum values:

        • unknown
        • active
        • complete
        • forceEnded
        • Changed property calibrationState (string)

          The calibration state of the session. Has value only for active session. Possible values: NoSession, NotStarted, InProgress, Complete

GET /users/{userId}/sessions/{sessionId}

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property status (string)

      The status of the session. Possible values: Active, Complete, ForceEnded

      Removed enum values:

      • unknown
      • active
      • complete
      • forceEnded

    • Changed property calibrationState (string)

      The calibration state of the session. Has value only for active session. Possible values: NoSession, NotStarted, InProgress, Complete

    • Deleted property chargeSpeed (number)
      The charge speed during the session in kw

GET /users/{userId}/sessions/{sessionId}/tariffs

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property tariffType (string)

      The tariff type. Values are: Standard, Peak, OffPeak, SuperOffPeak, Dynamic

      Removed enum values:

      • standard
      • peak
      • offPeak
      • superOffPeak
      • dynamic

GET /users/{userId}/vehicles

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    Changed items (object):

    • Changed property capabilities (array)

      Changed items (string):

      Removed enum values:

      • chargeState
      • stateOfCharge
      • charge
      • startStopDischarging
      • geoLocation
      • desiredStateOfCharge
      • pairing
      • departureTimes
      • pullTelemetry
      • pushTelemetry
      • geoFencing
      • startStopCharging

    • Changed property chargeState (object)

      • Changed property chargeState (string)

        Charge state of the vehicle. Possible values: Complete, Charging, Disconnected, Stopped

        Removed enum values:

        • unknown
        • complete
        • charging
        • disconnected
        • stopped

GET /users/{userId}/vehicles/{vehicleId}

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property capabilities (array)

      Changed items (string):

      Removed enum values:

      • chargeState
      • stateOfCharge
      • charge
      • startStopDischarging
      • geoLocation
      • desiredStateOfCharge
      • pairing
      • departureTimes
      • pullTelemetry
      • pushTelemetry
      • geoFencing
      • startStopCharging

    • Changed property chargeState (object)

      • Changed property chargeState (string)

        Charge state of the vehicle. Possible values: Complete, Charging, Disconnected, Stopped

        Removed enum values:

        • unknown
        • complete
        • charging
        • disconnected
        • stopped

GET /users/{userId}/vehicles/{vehicleId}/sessions/last

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property status (string)

      The status of the session. Possible values: Active, Complete, ForceEnded

      Removed enum values:

      • unknown
      • active
      • complete
      • forceEnded

    • Changed property calibrationState (string)

      The calibration state of the session. Has value only for active session. Possible values: NoSession, NotStarted, InProgress, Complete

    • Deleted property chargeSpeed (number)
      The charge speed during the session in kw

GET /users/{userId}/vehicles/{vehicleId}/state

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property chargeState (string)

      Charge state of the vehicle. Possible values: Complete, Charging, Disconnected, Stopped

      Removed enum values:

      • unknown
      • complete
      • charging
      • disconnected
      • stopped

GET /users/{userId}/charging-locations/{chargingLocationId}/tariffs

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property tariffs (array)

      Tariffs of the charging location

      Changed items (object):

      • Changed property type (string)

        Type of the tariff. Values are: Standard, Peak, OffPeak, SuperOffPeak, Dynamic

        Removed enum values:

        • standard
        • peak
        • offPeak
        • superOffPeak
        • dynamic

PUT /users/{userId}/charging-locations/{chargingLocationId}/tariffs

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property tariffs (array)

      Tariffs of the charging location

      Changed items (object):

      • Changed property type (string)

        Type of the tariff. Values are: Standard, Peak, OffPeak, SuperOffPeak, Dynamic

        Removed enum values:

        • standard
        • peak
        • offPeak
        • superOffPeak
        • dynamic

POST /users/{userId}/charging-locations/{chargingLocationId}/tariffs

Create tariff settings v2

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json

    • Changed property tariffs (array)

      Tariffs of the charging location

      Changed items (object):

      • Changed property type (string)

        Type of the tariff. Values are: Standard, Peak, OffPeak, SuperOffPeak, Dynamic

        Removed enum values:

        • standard
        • peak
        • offPeak
        • superOffPeak
        • dynamic

GET /users

List all users in pages

Parameters:

Added: createdFrom in query

Added: createdTo in query

Added: pageSize in query

Added: pageIndex in query

Return Type:

Changed response : 200 OK

Success

  • Changed content type : application/json