Skip to content

Commit d05d402

Browse files
odsododsod
committed
feat: add remote maintenance v3 API
1 parent b66ba6c commit d05d402

File tree

9 files changed

+3518
-0
lines changed

9 files changed

+3518
-0
lines changed

‎api/remotemaintenancev3/01-original.yaml‎

Lines changed: 1046 additions & 0 deletions
Large diffs are not rendered by default.

‎api/remotemaintenancev3/02-overlayed.yaml‎

Lines changed: 751 additions & 0 deletions
Large diffs are not rendered by default.

‎api/remotemaintenancev3/config.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
2+
package: remotemaintenancev3
3+
4+
output: remotemaintenancev3.gen.go
5+
6+
generate:
7+
models: true
8+
9+
compatibility:
10+
always-prefix-enum-values: true
11+
12+
output-options:
13+
skip-prune: true
14+
name-normalizer: ToCamelCaseWithInitialisms
15+
initialism-overrides: true

‎api/remotemaintenancev3/generate.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
package remotemaintenancev3
2+
3+
//go:generate echo [remotemaintenancev3] copying original...
4+
//go:generate cp remote_maintenance_support_api.yaml 01-original.yaml
5+
6+
//go:generate echo [remotemaintenancev3] applying overlay...
7+
//go:generate sh -c "go tool -modfile ../../tools/go.mod openapi-overlay apply overlay.yaml 01-original.yaml > 02-overlayed.yaml"
8+
9+
//go:generate echo [remotemaintenancev3] generating code...
10+
//go:generate go tool -modfile ../../tools/go.mod oapi-codegen -config config.yaml 02-overlayed.yaml

‎api/remotemaintenancev3/overlay.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
overlay: 1.0.0
2+
3+
info:
4+
title: Overlay for Mercedes-Benz Remote Maintenance Support API v3
5+
version: 1.0.0
6+
7+
actions:
8+
- target: $.paths
9+
description: "Skip code generation for requests"
10+
remove: true
11+
12+
- target: $.components.responses
13+
description: "Skip code generation for responses"
14+
remove: true
15+
16+
- target: $.components.securitySchemes
17+
description: "Skip code generation for security schemes"
18+
remove: true
19+
20+
- target: $.components.parameters
21+
description: "Skip code generation for parameters"
22+
remove: true
23+
24+
- target: $..[?(@.format == "uuid")].format
25+
remove: true
26+
27+
- target: $..[?(@.type=="array")]
28+
description: "Skip pointer to Go slices"
29+
update:
30+
x-go-type-skip-optional-pointer: true
31+
x-omitzero: true
32+
33+
- target: $..[?(@.deprecated)]
34+
description: "Remove deprecated properties and schemas"
35+
remove: true
36+
37+
- target: $..[?(@.type=="string")]
38+
description: "Skip optional pointer for strings"
39+
update:
40+
x-go-type-skip-optional-pointer: true
41+
42+
- target: $..[?(@.format=="date-time")]
43+
description: "Skip optional pointer for timestamps"
44+
update:
45+
x-go-type-skip-optional-pointer: true
46+
x-omitzero: true

‎api/remotemaintenancev3/remote-maintenance.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Remote Maintenance Support API Reference
2+
3+
This is an easy step-by-step guide that shows you how to use the Remote Maintenance Support API. For advanced usage, you can find detailed information about parameters and their values in the [Specification](https://developer.mercedes-benz.com/apis/remote_maintenance_api/specification) area. For generating clients you can also download the openAPI specification (swagger files) there.
4+
5+
API Endpoint
6+
7+
```http
8+
https://api.mercedes-benz.com/remotemaintenance/v3/
9+
```
10+
11+
## Authentication
12+
13+
This API is secured with OAuth 2.0. You will need a valid client ID and client secret to use this API and obtain a valid access token for your end-users, which you need to include in your API calls. You can find detailed documentation on how to use APIs secured with OAuth 2.0 and obtain an access token on the [OAuth documentation](https://developer.mercedes-benz.com/content-page/oauth-documentation) page.
14+
15+
You can manage and view your client credentials in the [console](https://developer.mercedes-benz.com/console). Your client credentials carry many privileges, so be sure to keep them secure! **Do not share your secret client credentials** in publicly accessible areas such GitHub, client-side code, and so forth.
16+
17+
All API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP will fail. API requests without authentication will also fail.
18+
19+
Example Header
20+
21+
```bash
22+
-H "authorization: Bearer <insert_the_access_token_here>"
23+
```
24+
25+
### Required Scopes
26+
27+
For the OAuth calls, you need to incorporate the following scope when requesting authorization from the user:
28+
29+
- _mb:vehicle:rms:reader_ - Maintenance relevant data of your vehicle: The third party provider receives remote access to maintenance-relevant of your vehicles data (e.g. the actual mileage) over the air via the built in SIM card.
30+
31+
32+
The [OAuth documentation](https://developer.mercedes-benz.com/content-page/oauth-documentation) page contains more details on how to request these scopes.
33+
34+
| | |
35+
|---|---|
36+
|Note|Remote Maintenance Support data retrieved by using this API is personal data within the meaning of the GDPR. Therefore, please adhere to the terms of use and data protection regulations within the general terms and conditions of the Remote Maintenance Support API when using this data.|
37+
38+
## Remote Maintenance Support
39+
40+
The Remote Maintenance Support API will provide the possibility for accredited 3rd party applications to access maintenance relevant vehicle data remotely on behalf of the Mercedes-Benz customer. To use the endpoints you need a valid VIN/FIN (**vehicleId**).
41+
42+
### 1. Get the Available Resources That Can Be Read Out
43+
44+
You can use the **resourceReadouts** resource of the Remote Maintenance Support API to get the resources that are available for readout. The response contains the available resources for the corresponding car. You can specify the car using the vehicleId path parameter in the request and verify the timestamp of the existing maintenance relevant data without using credits
45+
46+
**Content Description**
47+
**id**: Unique Id of the readout
48+
**asyncStatus**: Reflects the status of the readout
49+
**receivedTimestamp**: Timestamp at which the data received the server. If the value is “-“ it means that there is no data available. You can than call the Vehicle Data Readout Refresh to get new data from the vehicle.
50+
**messageTimestamp**: Timestamp of the API request
51+
**vehicleId**: The vehicle identifier of the extended vehicle, e.g VIN
52+
**resources**:
53+
name: Reflects the name of the resource
54+
version: Reflects the version of the resource
55+
api: Reflects the URL of the /resourceReadouts endpoint
56+
57+
Example Request
58+
59+
```bash
60+
curl
61+
-X POST "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/<insert_your_vehicle_id_here>/resourceReadouts"
62+
-H "accept: */*"
63+
-H "authorization: Bearer <insert_the_access_token_here>"
64+
-H "Content-Length:0"
65+
```
66+
67+
Example Response
68+
69+
```json
70+
{
71+
"resourceReadout": {
72+
"id": "exvs2510264021768535",
73+
"asyncStatus": "Complete",
74+
"receivedTimestamp": "2020-09-01T15:28:59+00:00",
75+
"messageTimestamp": "2020-09-08T07:26:24+00:00",
76+
"vehicleId": "WDD111111CAR01000",
77+
"resources": [
78+
{
79+
"name": "Value Readout",
80+
"version": "1.0.0.0",
81+
"api": "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/WDD111111CAR01000/valueReadouts"
82+
},
83+
{
84+
"name": "Warning Indicator Readout",
85+
"version": "1.0.0.0",
86+
"api": "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/WDD111111CAR01000/language/{language}/warningIndicatorReadouts"
87+
},
88+
{
89+
"name": "Vehicle Data Readout Refresh",
90+
"version": "1.0.0.0",
91+
"api": "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/WDD111111CAR01000/vehicleDataReadoutRefresh"
92+
}
93+
]
94+
}
95+
}
96+
```
97+
98+
### 2. Read RMS Value Readout
99+
100+
You can use the **valueReadouts** resource: Read mileage, service code and workshop code for Mercedes-Benz vehicles.
101+
102+
**Content Description**
103+
**asyncStatus**: Reflects the status of the readout
104+
**id**: Unique Id of the readout
105+
**messageTimestamp**: Timestamp of the API request
106+
**receivedTimestamp**: Timestamp at which the data received the server
107+
**vehicleId**: The vehicle identifier of the extended vehicle, e.g VIN
108+
**odometerValue**: Mileage of the vehicle
109+
**serviceCode**: The code for Cars and Vans to specify which maintenance type has to be done, e.g. A or B.
110+
**workshopCode**: The code to define which maintenance steps have to be done.
111+
**timeToService**: The remaining time in [days] to the next service.
112+
**distanceToService**: The remaining distance in [km] to the next service. Only available for passenger cars and vans.
113+
114+
Example Request
115+
116+
```bash
117+
curl
118+
-X POST "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/<insert_your_vehicle_id_here>/valueReadouts"
119+
-H "accept: */*"
120+
-H "authorization: Bearer <insert_the_access_token_here>"
121+
-H "Content-Length:0"
122+
```
123+
124+
Example Response
125+
126+
```json
127+
{
128+
"valuereadout": {
129+
"id": "exvs5719578132647805",
130+
"asyncStatus": "true",
131+
"messageTimestamp": "2020-07-01T14:14:07+00:00",
132+
"receivedTimestamp": "2020-07-01T14:14:07+00:00",
133+
"vehicleId": "WDD111111CAR01000",
134+
"maintenanceData": [
135+
{
136+
"odometerValue": "12153.0 km",
137+
"serviceCode": "A",
138+
"workshopCode": "505",
139+
"timeToService": "101.0 d",
140+
"distanceToService": "13091.0 km",
141+
"maintenanceData": [
142+
{
143+
"type": "Reifendruecke",
144+
"name": "Tirepressures",
145+
"line": [
146+
{
147+
"type": "TirePressureFrontLeft",
148+
"value": {
149+
"doublevalue": 2.7,
150+
"unit": "bar"
151+
}
152+
},
153+
{ ... }
154+
]
155+
}
156+
]
157+
}
158+
]
159+
}
160+
}
161+
```
162+
163+
### 3. Read RMS Warning Indicator Readout
164+
165+
You can use the **warningIndicatorReadouts** resource to read maintenance relevant warning lamps and event messages for passenger cars and vans.
166+
167+
**Content Description**
168+
**asyncStatus**: Reflects the status of the readout
169+
**id**: Unique Id of the readout
170+
**messageTimestamp**: Timestamp of the API request
171+
**receivedTimestamp**: Timestamp at which the data received the server
172+
**vehicleId**: The vehicle identifier of the extended vehicle, e.g. VIN
173+
**warningIndicatorReadouts_status**: Reflects the status of the Warning Indicator
174+
**warningIndicatorReadouts_originalOdometerValue**: Mileage when the Warning Indicator occurred the first time
175+
**warningIndicatorReadouts_mostRecentOdometerValue**: Mileage when the Warning Indicator occurred the last time
176+
**warningIndicatorReadouts_frequencyCounter**: How many times the Warning Indicator occurred. If it’s 1.0, than originalOdometer and mostRecentOdometer are the same
177+
**warningIndicatorReadouts_ignitionCycleCounter**: Indicates the number of consecutive operation cycles recorded since a Warning Indicator first became stored
178+
**warningIndicatorReadouts_text_symptomText**: Headline of the Warning Indicator
179+
**warningIndicatorReadouts_text_descriptionText**: The description of the Warning indicator of the digital manual with treatment recommendation
180+
**warningIndicatorReadouts_icon**: If available, the icon as base64 encoded. Decode to get the icon
181+
182+
Example Request
183+
184+
```bash
185+
curl
186+
-X POST "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/<insert_your_vehicle_id_here>/language/<insert_your_language_id>/warningIndicatorReadouts"
187+
-H "accept: */*"
188+
-H "authorization: Bearer <insert_the_access_token_here>"
189+
-H "Content-Length:0"
190+
```
191+
192+
Example Response
193+
194+
```json
195+
{
196+
"warningIndicatorReadout": {
197+
"id": "exvs4934615106146365",
198+
"asyncStatus": "Complete",
199+
"receivedTimestamp": "2020-09-01T15:28:59+00:00",
200+
"messageTimestamp": "2020-09-08T08:13:20+00:00",
201+
"vehicleId": "WDD111111CAR01000",
202+
"warningIndicators": [
203+
{
204+
"status": "STATUS_NOT_ACTIVE",
205+
"originalOdometerValue": "9904.0 km",
206+
"mostRecentOdometerValue": "9904.0 km",
207+
"frequencyCounter": "1",
208+
"ignitionCycleCounter": "3",
209+
"text": {
210+
"symptomText": "There is insufficient brake fluid in the brake fluid reservoir.",
211+
"descriptionText": "Example text"
212+
},
213+
"icon": "data:image/png;base64,example"
214+
}
215+
]
216+
}
217+
```
218+
219+
### 4. Vehicle Data Readout Refresh
220+
221+
Optional function, which can be used in case of an outdated timestamp (“resourceReadouts” output), to receive a new vehicle data readout. The prerequisite for using the function for passenger cars is the additional activation of “Remote Diagnosis” in the Mercedes me Portal by the vehicle owner. The function requests a new data record from the vehicle data memory of passenger cars.
222+
223+
**Content Description**
224+
**id**: Unique Id of the readout
225+
**asyncStatus**: Reflects the status of the readout
226+
**messageTimestamp**: Timestamp of the API request
227+
**vehicleId**: The vehicle identifier of the extended vehicle, e.g VIN
228+
**message**: A textual information that the request was successful or not
229+
230+
Example Request
231+
232+
```bash
233+
curl
234+
-X POST "https://api.mercedes-benz.com/remotemaintenance/v3/vehicles/<insert_your_vehicle_id_here>/vehicleDataReadoutRefresh"
235+
-H "accept: */*"
236+
-H "authorization: Bearer <insert_the_access_token_here>"
237+
-H "Content-Length:0"
238+
```
239+
240+
Example Response
241+
242+
```json
243+
{
244+
"vehicleDataReadoutRefresh": {
245+
"id": "exvs3033320330937090",
246+
"asyncStatus": "Complete",
247+
"messageTimestamp": "2019-11-05T11:49:09+0000",
248+
"vehicleId": "WDD111111CAR01000",
249+
"message": [
250+
{
251+
"message": "Request to refresh the vehicle data readout was successful"
252+
}
253+
]
254+
}
255+
}
256+
```
257+
258+
## General Error Handling
259+
260+
The API has a consistent error handling concept with the following error codes.
261+
262+
| **HTTP Error Code** | **Description** |
263+
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
264+
| 400 | The request could not complete due to malformed syntax. |
265+
| 401 | Invalid or missing authorization in header. |
266+
| 402 | Payment required. |
267+
| 403 | Forbidden. |
268+
| 404 | The requested resource was not found. |
269+
| 406 | The resource identified by the request is not capable of generating a response that matches the given Accept headers. |
270+
| 429 | Quota limit is exceeded. |
271+
| 500 | An error occurred on the server side, e.g. a required service did not provide a valid response. |
272+
| 501 | The server does not support the functionality required. |
273+
| 503 | The server is unable to service the request due to a temporary unavailability condition. |
274+
| 505 | The server does not, or refuses to support the protocol associated with the request. |

0 commit comments

Comments
 (0)