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.

Post Callback #

The first step is to configure a reusable configuration settings named callback.

1
2
3
4
5
6
7
8
9
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v3/fleets/{fid}/remote/callbacks' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --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
{
  "label": "<callback-name>",
  "callback": {
    "webhook": {
      "target": "https://my.post.callback",
      "name": "<webhook-name>",
      "batch": { "enabled": true, "size": 100 },
      "attributes": [ { "type": "Header", "key": "X-Vehicle_Id", "value": "$vin"} ]
    },
  "retryPolicy": { "policy": "None", "retryNumber": 3, "retryDelay": 10 },
  "batchNotify": { "size": 0, "timeWindow": 60 },
  "remoteTypes": ["Horn", "Doors"]
  
}

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

• label is the name of the callback. 
• callback.webhook: to set up the reception server and the notification attributes (headers, query params, body, usually use for routing).
• retryPolicy to configure how to deal with a server not receiving notifications. Retry Policy is described in this dedicated page.
• batchNotify if notifications needs to be received in batches instead of one by one.
• remoteTypes allows to set up which type of remotes can work with this callback.

Be careful: it’s only possible to send one remote action at once. However, callbacks are re-usable for multiple those remote action.

Example of Callback

This example creates a callback named “my-post-callback” with the following parameters:

• If the callback notification is not received, the request will be sent again every 120s until it’s properly delivered.
• The callback will be sent once 10 callback notifications are ready to be sent or 300s after triggering.
• The callback will be sent to https://my.post.callback webhook, with the VIN of the vehicle as a query path parameter and the Basic authentication in HTTP headers.
• This callback can be used in order to send remote actions: ThermalPreconditioning & ElectricBatteryChargingRequest.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "retryPolicy": { 
    "policy": "Always", "maxRetryNumber": 3, "retryDelay": 120
  },
   "batchNotify": { "size": 10, "timeWindow": 300 },
   "callback": {
      "webhook": {
         "target": "https://my.post.callback",
         "name": "My_Webhook",
         "attributres": [
            {
              "type":"Header",
              "key":"Authorization",
              "value":"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
            }
         ]
      }
   },
   "label": "my-post-callback",
    "notificationTypes": [
        "ThermalPreconditioning",
        "ElectricBatteryChargingRequest"
    ]
}

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:

• {fid} is the id of the fleet.
• {vid} 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
$ curl \
  --request POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/v3/fleets/{fid}/vehicles/{vid}/callbacks/{cbid}/remotes' \
  --data-urlencode 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --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
{
  "label": "remote_name",
  "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.

• <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 #