Guides

Sessions

The Sessions module handles all tasks related to sessions -
from starting a session and stopping it to history and payment.

Get Session history - POST

Retrieve a list of sessions for a specific user. It supports multiple filters and has pagination.

Endpoint: /v1/users/{userId}/sessions/history

API Reference

Parameters:

  • userId (path parameter, string)

Body fields:

  • sessionStatus (array of enums) - can be any of Statuses. If none specified, defaults to COMPLETE.
  • chargingKeyId (string)
  • startTime (iso datetime string)
  • endTime (iso datetime string)
  • cursor (string) – pass the cursor here to get next page. Iterate through pages until the cursor is absent from the response.
  • limit (integer, defaults to 50)

Example body:

{
  "sessionStatus": [
    "WAITING_TO_START", "STARTED"
  ],
  "chargingKeyId": "1234abcd",
  "startTime": "2022-04-04T08:30:00.000Z",
  "endTime": "2022-04-04T08:39:42.806Z",
  "cursor": "0",
  "limit": 50
}

Response fields:

  • sessions (array of Session objects) - Look at Session model for details.
  • cursor (string, optional) - use this cursor as a param in next request to get next page. If the cursor is absent, it means that the last page was reached.
  • count (integer)

Example response:

200 - OK

{
  "sessions": [
    {
      ... // Find Session model section below
    }
  ],
  "cursor": "1",
  "count": 22
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User not found
  • 500 - Internal Server Error

Get session by id - GET

Retrieve a session by its id. Session might be completed or not.

Endpoint: /v1/users/{userId}/sessions/{sessionId}

API Reference

Parameters:

  • userId – user to which sessions belong
  • sessionId

Look at Session model for the response and an example.

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User or session not found
  • 500 - Internal Server Error

Session model

Response fields:

* - Available only if session is in COMPLETE status

  • sessionStatus (string) - explained in more detail in Statuses
  • balanceStatus (string, optional) - can be one of ["PROCESSING", "PAID", "DEBT", "REFUND"]. Should be ignored for External Clearing.
  • charger (object)
    • chargingStationName (string)
    • connectorLabel (string)
    • evseId (string)
  • chargingKeyType (string, optional) - available only after a session has successfully started
  • connectorId (string, optional) - available only after a session has successfully started
  • duration * (string, optional) - string in ISO 8601 format.
  • energy (object, optional)
    • unit (string)
    • value (integer)
  • price * (object) - total, end-user price of a session
    • currencyCode (string) - 3-letter currency code
    • minorExclVat (integer)
    • minorInclVat (integer)
    • vat (string) - VAT percentage ex. "17.5"
  • receiptAvailable (boolean)
  • sessionId (string) - plugsurfing id of a session (Example: "pD8Yelb21vb")
  • site (string)
  • startTime (iso datetime string)
Example JSON:

200 - OK

{
  "sessionStatus": "COMPLETE",
  "balanceStatus": "PAID",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "chargingKeyType": "virtual",
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT15M",
  "energy": {
    "unit": "WH",
    "value": 1840
  },
  "price": {
    "currencyCode": "NOK",
    "minorExclVat": 0,
    "minorInclVat": 0,
    "vat": "25"
  },
  "receiptAvailable": false,
  "sessionId": "Zw4z33VbNYC",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-02-18T10:41:39.148Z"
}

Remote charging

To start a charging session remotely, use the endpoints provided below.

After starting or stopping a session, listen for Events to get updates about:

  • session starting
  • session failing to start
  • session stopping
  • session completing

The CDR (Charge Detail Record) is the most important and reliable piece of information. If you receive a CDR, it means the session ended successfully.

A session can be started remotely but stopped locally, for example from the car or by plugging out the cable.
It means that you might receive a SESSION_STOPPED event, a SESSION_COMPLETED even, or only a CDR.

Remarks

  • The order of events doesn't always follow the sequence outlined in the Statuses section. Events can occur in any order or be skipped entirely. Always consider the most recent update for the accurate status of the session.
  • Only chargers with "REMOTE_START_STOP_CAPABLE" capability can be started and stopped remotely.
  • Do not limit the possibility to start charging only to chargers in the "AVAILABLE" status. There can be a delay between status updates, so a charger might be available even if it still shows "OCCUPIED".
  • A session might stay in a certain state (like WAITING_TO_START or STOP_FAILED) for a long time. Ensure your product handles this appropriately and doesn't block the user from starting a session again in such cases.
  • After starting a session, all subsequent tries within the next 60 seconds on the same connector are blocked to avoid spamming the CPO with requests. Consider this when designing your integration.
  • It is possible to have two or more ongoing sessions simultaneously.

Possible problems

Connections with chargers are not always reliable and stable. Therefore, some errors may occur when using remote start/stop:

  • Session Starting Delays:

    • Starting a session can take some time. Allow up to two minutes for the session to transition from WAITING_TO_START to STARTED. Some chargers only unlock the cable after starting, so it will stay in WAITING_TO_START until the user connects the cable to their car.
    • If a charger can't start a session due to connectivity problems or issues with connecting to the car, wait at least one minute before allowing the user to attempt starting a session again.
    • If a session stays in WAITING_TO_START for more than two minutes, consider it failed and allow starting another one.

  • Session Failures:

    • If the charger didn't receive the stop request and charging continues while the session is marked as failed, the user should be able to send a STOP request again.
    • If a session stays in STOP_FAILED status for a few minutes, the user should still be able to start another session.
    • If a charger received a stop request but a timeout occurred and the session is marked as STOP_FAILED, another event about the session being stopped or completed should follow.

  • Mixed Session Outcomes:

    • It is possible to receive a SESSION_FAILED event followed by a SESSION_COMPLETE event and have a successful charging session. This can happen if there are connection issues between the charging point operator (CPO) and the charger, but the charger was still able to charge.
    • If a session doesn't stop correctly after a few tries, allow the user to abandon the session so that it is possible to start another one.

Start remote session - POST

Start a remote charging session on a given connector id.

Endpoint: /v1/users/{userId}/sessions/start

API Reference

Parameters:

  • userId (path parameter, string)

Request body:

  • connectorId - (string)

Example body:

{
  "connectorId": "ABcDefG"
}

Response fields:

  • sessionId (string)

Example response:

200 - OK

{
  "sessionId": "hiJKlMn"
}

Error responses

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User not found
  • 500 - Internal Server Error

Stop remote session - POST

Stop a remote charging session by providing a session id. Only sessions started remotely can be remotely stopped.
Remotely started sessions have the chargingKeyType field set to virtual.

Endpoint: /v1/users/{userId}/sessions/{sessionId}/stop

API Reference

Parameters:

  • userId (path parameter, string)
  • sessionId (path parameter, string)

Example response:

200 - OK (no body)

Error responses

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User not found
  • 500 - Internal Server Error

Session statuses

The status Enum should be designed to accept unknown values. In case a new status is introduced, handle these unknown values as FAILED.

  • CREATED – this is a transitive state, which occurs for a very short time
  • WAITING_TO_START – session is starting (only for Remote Charging)
  • STARTED – indicates an ongoing session
  • WAITING_TO_STOP – session is stopping (only for Remote Charging)
  • STOP_FAILED – stopping a session failed – it should allow the user to stop a session again (only for Remote Charging)
  • STOPPED – session has ended, but the CDR was not yet received
  • COMPLETE – session is fully completed and priced
  • FAILED – session had problems starting
  • REFUNDED
  • UNKNOWN – should be handled like 'FAILED' status
Session statuses flow

Session statuses flow

Testing remote charging

To test successful and/or failed remote charging you need to pass specific connectorId in your request body.
The provided example connector IDs are applicable to the stage environment.

Steps to test remote charging
  1. Find a charger via geosearch
  2. Select an available charger and get it sconnector id
  3. Start the session
  4. Wait a desired amount of time
  5. Stop the session

Below, you will find details on how to test a successful session and how to simulate error scenarios.

Successfully started session

Locations found close to these coordinates can be used to simulate a correct session:

Latitude: 52.290056
Longitude: 20.907028
Distance: 500
Geosearch request

Firstly search for locations around these coordinates:

curl -X 'POST' \
  'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.290056&longitude=20.907028&radius=500' \
  -H 'X-API-Key: <apiKey>'
Start session

Pick any connector with "AVAILABLE" status and start a session:

curl -X POST --location "https://drive-api-stage.plugsurfing.com/drive/v1/users/<userId>/sessions/start" \
    -H "x-api-key: <apiKey>" \
    -H "Content-Type: application/json" \
    -d "{
          \"connectorId\": \"RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsawwqypdT1Qwa3ck8cchZpEH2JGytmok239REYlPWleVQ==\"
        }"

A session id will be returned.

Example session object

After requesting a session by id, a session in "STARTED" status should be returned.

{
  "sessionStatus": "STARTED",
  "charger": {
    "chargingStationName": "Charge at the castle",
    "city": "Stockholm",
    "evseId": "SE*REM*E1000",
    "streetName": "Kungliga slottet"
  },
  "connectorId": "+YePNZexUkx8U9fCUoBEmu8EVhBUn1TWdxjd5Ky1ly1Tm3r2MApUUkDIzO4IqizV3l4XTQ87QmotRFvUW1SCWA==",
  "duration": "PT12.333S",
  "receiptAvailable": false,
  "sessionId": "NbmNQa80MwR",
  "site": "Charge at the castle",
  "startTime": "2023-02-24T13:14:14Z"
}
Error scenario:

There is one location designated for simulating errors, which is located at:

Latitude: 52.334242
Longitude: 20.899305

Below are 4 specific error scenarios which could be tested and the EVSE id
for which these error occurs.

  • Waiting to start hanging: DE*DRV*E6mayTt
  • Stop ignored (rejected): DE*DRV*E4JanRe
  • Start fails: DE*DRV*E9svnVs
  • Stop fails: DE*DRV*E8vsnVn

Below the error scenarios are described in more detail:

1. Waiting to start hanging:
  1. Select any connector id from evse_id DE*DRV*E6mayTt and initiate a charging session
  2. Obtain the session id from the response and get session details using session API request
  3. Status of charging should be WAITING_TO_START
Example request
 curl -X 'POST' \
  'https://drive-api-stage.plugsurfing.com/drive/v1/users/<userId>/sessions/start' \
  -H 'X-API-Key: <apiKey>' \
  -d '{
  "connectorId": "RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsYcqfRqeQ1Z/hmFFk/Lu+ZjAmz+8p9htX8Wmh0rzSdKGQ=="
}'
2. Stop ignored (rejected):
  1. Select any connector id from evse_id DE*DRV*E4JanRe and initiate a charging session
  2. Obtain the session id from the response and trigger a stop session
  3. Enter the same session id in get session API request and check the status
  4. Status of charging should still be STARTED as stop request is ignored
3. Start fails:
  1. Select any connector id from evse_id DE*DRV*E9svnVs and initiate a charging session
  2. Obtain the session id from the response and get session details using session API request
  3. Status of charging should be FAILED as starting a charging session failed
4. Stop fails:
  1. Select any connector id from evse_id DE*DRV*E8vsnVn and initiate a charging session
  2. Obtain the session id from the response and trigger a stop session
  3. Enter the same session id in get session API request and check the status
  4. Status of charging should be STOP_FAILED as stop request fails

Updated 2 months ago