Getting Started with EV Charging Session Service APIs

EMobility Charging API Product provides the option to manage charging at Shell Recharge locations. The end points provides control to start, stop and get status of the charging session.

Supported Functions

• Start a charging session
• Stop a charging session
• Retrieve the status of a charging session
• Retrieve the list of all active sessions for a card

All the APIs are authenticated with standard OAuth2.0

Authentication

Shell API’s are secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The end to end process is illustrated in the sequence diagram below.

This step is to generate the API Access Token using the unique Client ID and Client Secret provided by Shell. (Please note that this credentials is to validate the API request between Shell and its partner so its system to system access token)

Key Request Parameters

Once you receive the client ID & Secret, next step is to call the https://sso-uat.shell.com/as/token.oauth2 endpoint to authenticate. Following are the key parameters-

• Method: POST
• Authorization Type: OAuth 2.0
• Auth URI: https://sso-uat.shell.com/as/token.oauth2
• Client_Id: **** (OAuth Client ID)
• Client Secret: **** (OAuth Client Secret)
• Grant Type: client_credentials

Sample cURL Request

curl --location --request POST 'https://sso.shell.com/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=*************' \
--data-urlencode 'grant_type=client_credentials'

On receiving the request Shell Authorization system will verify all the parameters in the request and, if everything checks out, it will generate your access token and return it in the response.

Sample Response

{
    "access_token": "***********",
    "token_type": "Bearer",
    "expires_in": 7199
}

The response will contain the following parameters:

• access_token: The token to be used to call the functional APIs
• expires_in: The amount of seconds until the access token expires.
• token_type: Bearer

Exception Handling

All error scenarios are returned with a response body and identifier.

{
      "error_descrription": "invalid client or client credentials",
      "error": "invalid_client"
}

Start Session API

Introduction

This API initiates to start a session on a EVSE (Electric Vehicle Supply Equipment). When the EV Charge Card number and the unique EVSE ID on the location is provided, the session is initiated.

Please note that this is an asynchronous request, the request will be passed on to the operator/platform to be processed further.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

• Method : POST
• URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/start
• Headers :
  • client_id : API Client ID to be passed here
  • client_secret : API Client Secret to be passed here
  • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
  • Content-Type : application/json
• Body
  • evChargeNumber : The EV Charge Number which can be found on the back of the Shell EV Card
  • evseId : Standard EVSE (Electric Vehicle Supply Equipment) Id identifier (ISO-IEC-15118)

    Sample CURL Request

curl --location --request POST 'https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/start' \
--header 'client_id: ************' \
--header 'client_secret: ***********' \
--header 'Authorization: Bearer ********* \
--header 'Content-Type: application/json' \
--data-raw '{
 "evChargeNumber": "NL-TNM-216599-X",
 "evseId": "NL*TNM*EVIRTUALCP0002*0"
}'

Sample Response

:warning: HTTP 202 Success Response

{
    "sessionId": "2f0c91f5-9b17-481f-9a71-ce1d9d188998"
}

Retrieve Session

Introduction

This API retrieves the status and details of the session which was started by the user. The session ID generated earlier needs to be passed in this API in order to retrieve the status.

This end point could be used in order to check the current status of the session which was requested to start. EMAId (EMobility Account Identifier) which was generated unique to the user.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

• Method : POST
• URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/retrieve/{sessionId}
• Headers :
  • client_id : API Client ID to be passed here
  • client_secret : API Client Secret to be passed here
  • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
  • Content-Type : application/json

Sample CURL Request

   curl --location --request GET 'https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/retrieve/2f0c91f5-9b17-481f-9a71-ce1d9d188998' \
--header 'client_id: *******'' \
--header 'client_secret: *******'' \
--header 'Authorization: Bearer *******'

Sample Response

{
    "emaId": "NL-TNM-C0216599X-A",
    "evseId": "NL*TNM*EVIRTUALCP0002*0",
    "id": "2f0c91f5-9b17-481f-9a71-ce1d9d188998",
    "startedAt": "2022-02-22T10:46:38.975Z",
    "state": {
        "status": "started"
    },
    "userId": "96f69b3b-8ad4-487a-baaa-f1d3db741e88"
}

Stop Session

Introduction

This API stops a session by providing the session ID which was retrieved when starting the session. HTTP 202 response will be returned if the request is accepted. Once the session is stopped the response will contain the DateTime on which it is stopped.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

• Method : POST
• URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/stop/{sessionId}
• Headers :
  • client_id : API Client ID to be passed here
  • client_secret : API Client Secret to be passed here
  • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
  • Content-Type : application/json

Sample CURL Request

curl --location --request POST 'https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/stop/2f0c91f5-9b17-481f-9a71-ce1d9d188998' \
--header 'client_id: ********' \
--header 'client_secret: ********' \
--header 'Authorization: Bearer ********

Sample Response

HTTP 200 Response confirms that the session has been stopped.

"The request has been accepted for processing, but the processing has not been completed."

List of Active sessions

Introduction

This API retrieves the list of active sessions for a given set of EMAIds (EMobility Account Identifier)

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

• Method : POST
• URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/active
• Headers :
  • client_id : API Client ID to be passed here
  • client_secret : API Client Secret to be passed here
  • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
• Query Parameters :
  • emaIds : List of EMAIds (EMobility Account Identifier) generated unique for a particular user. (Multiple EMAIds can be passed as comma separated values)

Sample CURL Request

curl --location --request GET 'https://api01-uat.shell.com/mobility-ev-api/v1/api/charge-sessions/active?emaIds=NL-TNM-C0216599X-A' \
--header 'client_id: ******' \
--header 'client_secret: ******' \
--header 'Authorization: Bearer ******'

Sample Response

[
    {
        "emaId": "NL-TNM-C0216599X-A",
        "evseId": "NL*TNM*EVIRTUALCP0002*0",
        "id": "2f0c91f5-9b17-481f-9a71-ce1d9d188998",
        "startedAt": "2022-02-22T10:46:38.975Z",
        "state": {
            "status": "started"
        },
        "userId": "96f69b3b-8ad4-487a-baaa-f1d3db741e88"
    }
]