Stellantis Connected Car B2C API

openapi: 3.0.0
servers:
  - url: 'https://api.mpsa.com/api/connectedcar/v2'
info:
  version: '4.17.2'
  title: Groupe PSA Connected Car B2C API
  license:
    name: Groupe PSA Licence
    url: 'https://www.psa-peugeot-citroen.com/'
  description: >
   
    # Introduction:

    This is the description of the *Groupe PSA Connected Car B2C API*. 
    This specification is written in **OpenAPI Specification version 3** and can
    be displayed using [ReDoc](https://github.com/Rebilly/ReDoc) or
    [Swagger](http://swagger.io).
      This REST API allows  applications to fetch data from the connected Vehicles data  platform.
    
    ---
    
    # Authentication:
    
      PSA Connected Car APIs uses the [OAuth  2.0](https://tools.ietf.org/html/rfc6749) protocol for authentication and
      authorization. Any applications require a valid [Access Token](https://tools.ietf.org/html/rfc6749#section-1.4) to access to user data.
      The Implicit Grant Type is used to get the access token.
      
    ---
    
    # Scopes:
    
      ## Filtering Scopes
      - When the API caller requests a set of scopes. The owner may not grant access to all of the requested scopes, so the application will have to adapt to the restricted access or request for a larger set of scopes again.
      - API backend will deliver the data related to the granted scopes only. 
      - If no scope has been granted with the caller token then an unauthorized error will be returned.
          
        _If for example the API caller requests for "aggregated telemetry" or "trip" without having the "location" scope, then the resource data returned will not have the vehicle's position but only other data that will satisfy the scopes present in the token._
      
      ##  Use of Scopes
      - Scopes are specified  in each individual API.
      - Depending on the API, scope can be :
        - Mandatory (designed with comment "#Required"): if this scope is not used during the request an error will be returned. An API can have multiple mandatory scopes.
        - Optional scopes will return an optional part of the API.
      
      ## Hierarchical Scopes
      Since API resources are hierarchical, scope follow also this strategy.     
      **Scopes used to request access to resources for OAuth2 security scheme fall into four categories:**

      #### _1. <u>IoT data scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|
      |data:telemetry| Read full telemetry data|
      |data:position| Read vehicle  Location (position) data|
      |data:trip| Read trip related data|
      |data:alert| Read alert related data|
      |data:collision| Read collision related data|
      |data:vehicle:devices:pnc| Read vehicle Plug and Charge related data|

      #### _2. <u>Vehicle remotes scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|
      |remote:door:write| Read & send door remote (pending & history)|      
      |remote:preconditioning:write| Read & send door Lock remote (pending & history)| 
      |remote:horn:write| Read & send horn remote  (pending & history)| 
      |remote:charging:write| Read & send charging remote (pending & history)| 
      |remote:lights:write| Read & send lights remote (pending & history)| 
      |remote:wakeup:write| Read & send weackup remote (pending & history)| 
      |remote:navigation:write| Read & send navigation remote (pending & history)| 

    ---
    
    # Paging:
    
    To make this necessary feature easy to use when retrieving a collection of results, this API uses a token (computed and interpreted by the backend only) as a context that contains all necessary information allowing the navigation through pages. 
      Token acts as an ```HTTP COOKIE``` on the client-side, so the server does not keep any cache or session settings to continue paging and keep all request stateless.
          
    ---
    
    # Errors:
      Error codes returned by all APIs comply with the standard. Nevertheless, PSA Services (callers) need to have more detailed data structures (even when the answer is not Http-OK) to better categorize the type of error by providing application code, message and debugging code (for investigation purposes). The HTTP code of the response is managed by the protocol itself (in the header).
        
      ### These APIS are likely to report the following HTTP code:
      
      | <b>Code</b>  | <b>Description</b>  |  <b>Case</b> |  
      |---|---|---|
      | 200  |<i>The request has succeeded and the resource data has been sent.</i>|GET APIs.  |
      | 202  |<i>The request has been accepted for processing, but not yet acted upon. An id of processing is returned.</i>|POST/PUT requests:<br>-Create monitor<br>-Create a callbak.| 
      | 204  |<i>The request has been accepted and there is no additional content</i>|DELTE APIs:<br>-Delete monitor.<br>-Delete a callback.|
      |400|<i>Request cannot be processed due to invalid query parameter value of body content (for POST/PUT verbs)</i>|ALL APIs.|
      |401|<i>Unauthorized request due to lack of valid authentication credentials.</i>|All APIs.|
      |403|<i>Unauthorized request due to insufficient credentials to grant access.</i>|All APIs.|
      |404|<i>Target resource not found.|All APIs. Even POST, PUT or DELETE if the resource id is uncknown.</i>|
      |500|<i>Unexpected condition that prevented from fulfilling the reques.</i>|All APIs.|


      
      **Errors are  returned as a generic error response:** see ```ErrorCodeDefaultResponse``` model.
       
    ---
    
    # API Usage:
     
      ## Data output format
      
      **All APIs return data in JSON format. The application who uses them must take into account the evolving character of them and more precisely regarding the schemas of the exposed data. Indeed:**
      
      *  The missing of known data fields should not cause an error. 
      *  It should (correctly)  deal with JSON content with unknown properties also. Indeed, data schema extensions should be supported without errors even if they are not used. 
        
      
      **For example:**
      
      Assuming a given exposed resource with this data schema:
        
          
           data:
            type: object
            description: Data model
            properties:
              field1:
                type: string
              field2:
                type: number
             
      The application should be able to deal with those possible valid JSON contents:
        
      > All fields:
        ```{
          "field1":"value1",
          "field2": 1
        }```
        
      > Missing field2:
        ```{
          "field1":"value1"
        }```        

      > Unknow  field3:
        ```{
          "field1":"value1",
          "field3": 2.5
        }```
      
      ## Callback, Monitor & Remote management:
      - Creation on monitor, remote & subscribe (callback) will be associated to a client ID, user (and vehicle depending on the API requested), therefore:
        - Read operation will only return information previously created by this client ID, user and vehicle association
        - Update, delete operation will only be possible for ressource previously created by this client ID, user and vehicle association
      - A maximum of 5 monitors can be associated to a vehicle, client ID, user. 
    --- 
    
    
    
  
tags:
  - name: User
  - name: Vehicles
    description: Access to Vehicles details.
  - name: Trips
    description: Describe Trips of a a User or Vehicle
  - name: Subscribe
    description: Describe User subscription (callback) to use with remote and/or monitor feature.
  - name: Monitors
    description: Describe the vehicle monitor features.


# --- truncated at 32 KB (211 KB total) ---
# Full source: https://artifacts.apis.io/stellantis/openapi/stellantis-connected-car-b2c-api-openapi.yml