WEB API

accessing party for end-users

Remote - Set Up

Info: Stellantis Accessing Party for End-Users API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is available only on request.

This tutorial explains how to set up remotes using the REST API. In order to do so, we will need to understand how to configure the callback and send a remote command.

HTTP request headers used in this tutorial require to use realms.

Post Callback #

The first step is to configure a reusable configuration settings named callback. The same callback can be used for monitors and/or remote features of this API.

Registering a callback can be done using the following API. They are 3 types of callback notifications: WebHook, Push Notification, WebSocket.

1
2
3
4
5
6
7
8
9
10
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v4/user/callbacks' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-introspect-realm: <realm>' \
  --key 'path/to/key.pem' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "label": "<callback-name>",
  "type": ["Monitor", "Remote"],
  "callback": {
    "webhook": {
      "target": "https://my.post.callback",
      "name": "<webhook-name>",
      "batch": { "enabled": true, "size": 100 },
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin"} ]
    },
    "pushnotif": {
      "devices": ["<device_name>"],
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin"} ]
    },
    "websocket": {
      "target": "scheme://host[:port][/Path]",
      "batch": { "enabled": true, "size": 100 },
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin" } ]
    }
  }
}

Below is a description of the JSON body to configure the callback.

  • label is the name of the callback. 
  • type to declare a callback for Monitor, Remote or both.
  • callback allows to configure notifications, they can be of 3 different types:
    • webhook: for HTTP notification.
    • websocket: for websocket callbacks.
    • pushnotif: using Firebase Cloud Messaging in order to trigger push notification on iOS (APNs) or Android (GCM).
  • callback.<notification_type> allow to configure:
    • attributes: to setup additional attributes of the notification (headers, query params, body). These attributes are usually used for routing.
    • batch: webhook & websocket notifications can be send in batch, it’s recommended to use batch over single time notification.

If the callback is properly created the HTTP response body will look like:

1
2
3
4
5
{
  "_links": {  },
  "callbackId": "<id>",
  "status": "Running"
}

This message indicates that the callback has been sucessfully created with a unique identifier. This identifier, called {cbid} is required to create a remote.

Post Remote Request #

The following example is the structure of the HTTP request intended to send a remote command.

The following path parameters are required, they need to be replaced by the appropriate value:

  • {id} is the id of the vehicle to send a remote to.
  • {cbid} is the id of a callback, this id is received when a callback is created.
1
2
3
4
5
6
7
8
9
10
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v4/user/vehicles/{id}/callbacks/{cbid}/remotes' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-introspect-realm: <realm>' \
  --key 'path/to/key.pem' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \
1
2
3
4
5
6
7
8
{
  "label": "remote_name",
  "attributes": {  }
  "callbackAttributes": {  },
  "door": {
    "state": "Unlocked"
  }
}

Below is a description of the JSON body to configure the remote, refers to API Reference for the specification of this endpoint.

  • label is the name of the remote.

  • attributes & callbackAttributes: allows adding or to overwrite key/value attributes declared in the callback creation, it will be available in the notification as query parameters, headers or body. Attributes (vin, CallbackID & CallbackLabel) are useful to perform the routing of the notification.

  • <remote-type> objects allow configuring the remote action to send, checkout remote actions. Only one remote can be sent at once.

Post Remote Response #

This is an example of HTTP response when sending a remote action:

1
2
3
4
5
{
  "_links": {  },
  "remoteActionId": "909bkqacjb3bfhdhjanahbc244jj2lixfbe2e52u5y",
  "type": ["ThermalPreconditioning"]
}

This message indicates that the remote has been successfully created with a unique identifier. This identifier is sent with every notification; therefore, it allows tracking this remote.

Remote Actions #

Object Name Description Example
RemotePreconditioning Choose between immediate preconditioning or not, and set a program with recurrence or not, start time, occurence during the week then, choose to enable or not this program. Note: Using the key/value Slot it’s possible to register up to 4 PreconditionPrograms. { "label": "string", "preonditionning": { "airConditioning": { "immediate": false, "programs": [ { "recurrence": "Daily", "start": "PT14H30M", "occurence": { "day": [ "Mon" ] }, "slot": 0, "enabled": true } ] } } }
RemoteSetImmobilization Set activate to true to immobilize a vehicle. This feature can be used in addition to “RemoteSetStolen”. { "immobilization": { "activate": true } }
RemoteDoorsState Set state to Locked or Unlocked. { "door": { "state": "Unlocked" } }
RemoteHorn Honk the vehicle horn. { "horn": { "state": "Activated" } }
RemoteCharging It’s possible to choose between immediate recharge or nextDelayedTime with a timestamp RFC3339 before the charge activation. To stop a charge use set immediate to false. { "charging": { "nextDelayedTime": "string", "immediate": false } }
Stop: { "charging": {"immediate": false} }
RemoteSetStolen Set stolen to true to put the vehicle in stolen state. It’s mean that it will stay awake and refresh its position status on a regular basis. { "stolen": { "stolen": true } }
RemoteLights Set a light blinking. { "ligths": { "on": true } }
RemoteState Set action: state to retrieve an updated status of the vehicle. { "state": { "action": "state" } }
RemoteNavigation Set action: navigation to send a remote navigation on the guidance system of the vehicle. It’s possible to send a notification to the driver through the HMI, before launching the navigation with "driverApproval": true. The field "positions": [...] is an array of GeoJSON points where the last point is the final destination and the other points are waypoints, maximum 10 points. {"navigation": { "driverApproval": true, "positions": [ { "type": "Point", "coordinates": [ 5.970338, -62.536239 ] } ]}}