WEB API

for fleet owner

Remote - Set Up

Info: Stellantis Fleet Owner API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is made for organisations owning fleet of vehicles.

1. Post Remote CallBack #

Callback Request

Before being able to send a remote action, you have to configure the HTTP callback that will be sent to your webhook.

This callback specifies your webhook config, a retry policy and a batch notification policy. You can set up several callbacks. You will then execute a remote action using the callback the most appropriate for the situation.

Here is an overview of an HTTP request intended to create a remote callback.

1
2
3
4
5
6
7
8
9
$ curl \
  --POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/{version}/fleets/{fid}/remote/callbacks' \
  --data 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --key 'path/to/key.pem' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \
1
2
3
4
5
6
7
{
  "retryPolicy": { },
  "batchNotify": { },
  "callback": { },
  "label": "callback-name",
  "extendedEventParam": [ ]
}

Below is a description of the JSON models explaining how to configure a callback. Please refer to API Reference models to read a full description of the callback configuration.

  • RemoteCallbackSubscribe: this JSON object allow you to configure your remote callback:
    • retryPolicy: this where you set retry policy, it’s in case your webhook has not received the callback, whatever is the reason.
    • batchNotify: you can set this object in case you need to receive notification in batch instead of one by one.
    • callback>webhook: this required object is where you will set the address and name of your webhook. This is also where you can customize the HTTP notification (example: for authentication purpose).
  • notificationTypes: this array of remotes allow you to subscribe this callback to one or more actions.

Example

This request ask to create 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 your https://my.post.callback webhook with the vin of the vehicle as a query path param and your Basic authentication in HTTP header.
  • 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
25
26
27
28
29
{
   "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"
    ]
}

Callback Response

Here is an example of HTTP response after POSTING a new remote callback.

1
2
3
4
5
{
    "_links": {...},
    "callbackId": "c7eeaafdf0ab9683d5a1b8d51572014996540m0021",
    "status": "Running"
} 

The callback have been created with id=c7eeaafdf0ab9683d5a1b8d51572014996540m0021. This callbackId will be sent with every notification to your webhook.

Important: You will need this ID to POST a remote action to a vehicle with this callback.

2. Post Remote Action #

Remote Request

Once you have a dedicated callback, you are able to POST a remote action to a vehicle. Choose a vehicle id (you can retrieve it with the API status), then send this kind of request:

1
2
3
4
5
6
7
8
9
$ curl \
  --POST \
  --url 'https://api-cert.groupe-psa.com/connectedcar/{version}/fleets/{fid}/vehicles/{vid}/callbacks/{cbid}/remotes' \
  --data 'client_id=<client_id>' \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --cert 'path/to/client_cert.pem[:<cert_password>]' \
  --key 'path/to/key.pem' \
  --cacert 'path/to/ca_cert.pem' \
  --data '<check out HTTP body>' \
1
2
3
4
5
6
{
  "label": "remote_name",
  "door": {
    "state": "Unlocked"
    }
}

In this API you have to replace this fields:

  • {fid} is the id of your fleet.
  • {vid} is the id of the vehicle to which you want to send the remote action.
  • {cbid} is the id of one of your callbacks (see 1. Post remote Callback).

You can browse the Remote Object in the reference section to have more info about how to send a specific remote action:

Remote Actions

Object Name Description Example
RemotePreconditioning Choose between immediate preconditionning 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 you can 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 to activate to true if you need to immobilize a vehicle. You can use this feature in addition to “RemoteSetStolen”. { "immobilization": { "activate": true } }
RemoteDoorsState Set state to Locked or Unlocked. { "door": { "state": "Unlocked" } }
RemoteHorn Honk the vehicel horn. { "horn": { "state": "Activated" } }
RemoteCharging You can 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 if you want the vehicle to be in stolen state. It’s mean that it will stay awake and refresh lastPosition 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. You can choose 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 ] } ]}}

Be careful: you can send only one Remote Action at once. If you need to send several Remote Actions you have to send several HTTP POST requests to /fleets/{fid}/vehicles/{vid}/callbacks/{cbid}/remotes. However, you can use the same callback for those Remote Action.

Remote Response

This is an example of HTTP response when you POST remote action:

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

RemoteActionID is the unique identifier of the remote. This id will be sent to your callback with your remote action reports.