Getting Started with Shell Mobility System (SMS) APIs
Shell Mobility Systems (SMS) allows you to send and receive all the mobility tasks, data, and insights that you need without leaving your system.
Scenarios that you can do on your internal platform include:
- Create Work Order
- Update Work Order
- Retrieve Work Order
- Cancel Work Order
SMS consumes the API, optimizes the logistics, allocates the task to the operatives' mobile application and executes on the ground. This API also enables to view live updates from the SMS dashbooard on your Work Order status, images and relevant documents.
The below table represents the set of APIs that Shell offers to create and manage the work order in SMS system.
API End Point | API Functionality |
---|---|
POST /job | Customer creates the work order by entering all the details required for the SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operatives via mobile application and executes on the ground |
GET /jobs/{jobId} | Get the details of a particular work order |
PUT /jobs/{jobId}/customer | To update the customer details for the specific work order |
PUT /jobs/{jobId}/vehicle | To update the vehicle details for the specific work order |
POST /jobs/{jobId}/cancel | Customer updates existing work order to cancel. SMS consumes the API and removes the associated tasks from the system |
PUT /jobs/{jobId}/slotBooking | Customer can book any of the available slot for the scheduled work order. SMS consumes the API, optimizes the logistics, allocates the task to the operatives via mobile application and executes on the ground |
PUT /jobs/{jobId}/woSchedule | Customer can schedule existing work order for specific date or time. SMS consumes the API, optimizes the logistics, allocates the task to the operatives via mobile application and execute on the ground |
PUT /jobs/{jobId}/woReschedule | Customer updates existing work order to an alternative date and/or time. SMS consumes the API, optimizes the logistics, allocates the task to the operatives via mobile application and executes on the ground |
GET /accounts/{accountId}/locations | Get the list of all the MCC locations for the customer account |
GET /accounts/{accountId}/workTypes | Get the list of all the work order and sub work order types of the specific customer account |
Authentication Service
OAuth 2.0 is the preferred method of authentication to access the APIs. OAuth 2.0 allows authorization without the external application getting the user's email address or the password. Instead, the external application gets a token that authorizes access to the user's account. All the SMS APIs are secured/protected using standard OAuth 2.0.
The end-to-end process is illustrated in the sequence diagram below.
The above step is to generate API Access Token using the unique Client ID and Client Secret provided by Shell.
Note: The credentials is to validate the API request between Shell and its B2B Customer, so it is system-to-system access token.
Key Request Parameters
Once you receive the Client ID and the Client Secret, the next step is to call the below OAuth 2.0 endpoint to generate the access token <[https://sso-uat.shell.com/as/token.oauth2]>
The key request details for the OAuth 2.0 endpoint are:
Element | Value |
---|---|
Method | POST |
Authorization Type | OAuth 2.0 |
Auth URI | [https://sso-uat.shell.com/as/token.oauth2] |
Client_Id | ****(OAuth ClientID) |
Client Secret | ****(OAuth Client Secret) |
Grant Type | client_credentials |
Sample cURL Request
curl -X POST\
'https://sso-uat.shell.com/as/token.oauth2'\
-H 'authorization: Basic sadasdasdasdadadasdasd=='\
-H 'content-type: application/x-www-form-urlencoded'\
-d grant_type=client_credentials'\
--data-urlencode 'client_secret=*************'\
--data-urlencode 'grant_type=client_credentials'
On receiving the requests, Shell Authorization system verifies all the parameters in the request and, if everything checks out, then it will generate your access token and return it in the response.
Sample Response Body
{
"access_token": "***********",
"token_type": "Bearer",
"expires_in": 7199
}
The response parameter and the description are:
Parameter | Description |
---|---|
access_token | The access token to be used to call the functional APIs |
expires_in | The number of seconds until the access token expires |
token_type | Bearer |
Exception Handling
All the error scenarios are returned with a response body and identifier.
{
"error_description": "invalid client or client credentials",
"error": "invalid_client"
}
HTTP Status Code | Description | Scenarios |
---|---|---|
400 | Bad Request | |
401 | Unauthorized |
Create Work Order Service
Introduction
Customer creates the work order by entering all the details required for SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operative via mobile application and executes on the ground by the operative.
Customer has to provide the below details to create the work order.
- The address location of the user
- Customer details
- Location, where the service is required
- Date, when the service is required
- Vehicle details
The end-to-end process is illustrated in the sequence diagram below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | POST |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/jobs |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
Content-Type | Content-Type entity header is used to indicate the media type of the resource i.e., application/json |
Customer creates the work order by entering the mandatory fields depends on the business scenarios.
The below tables represents the functionality of all the fields available in Create Work Order request.
Create Work Order Request Payload Fields
Field | Description | Data Type | Examples |
---|---|---|---|
accountId | Unique account ID required to identify the customer | String | 0019E00001jzZFQQA2 |
workTypeId | Indicates the type of work order | String | 08q9E000000Do7yQAC |
orderNumber | Unique ID.Note: The Fleet customer creates the order number that can be used as reference | String | LMB143082152176 |
linkedWorkOrderId | Work order ID of the linked work order | String | 44363949 |
jobDate | The preferred start date and end date of the job | Date format: YYYY-MM-DD | 2022-12-28 11:00:00 |
countryISOCode | The ISO code of the country, of the job address | String | FRA |
addInstr | Any other additional instruction. Note: Fleet customer enters any additional instructions required for the service operative to know and to exceute the task | String | Get documents signed |
firstName | The first name of the end customer whose the job has booked | String | John |
lastName | The last name of the end customer whose the job has booked | String | Smith |
customerIdentification | Government approved customer identification that can be used to authenticate the end user | String | License number: 100071452 |
customerMobile | Customer Mobile Number.Note: The service operative can use the customer mobile number to communicate and to share the job updates with them | Number | 34722436539 |
mobileCountryCode | Defines the Mobile dialing code for the country | String | 33 |
contractType | Type of Contract | String | Contract type: Lease |
subWorkTypeId | ID which defines the service appointment | String | 23454 |
locationId | ID which identifies the location of the station | String | 1309E000000DRtmQAG |
Street | The street name of either the customer address or a MCC location | String | Rue du Panier |
City | The city or town of either the customer address or a MCC location | String | Marseille |
zipCode | The postal code or zipcode of either the customer address or a MCC location | String | 13001 |
Country | The country name of either the customer address or a MCC location | String | France |
Latitude | The latitude of either the customer address or a MCC location | String | 43.304585 |
Longitude | The longitude of either the customer address or a MCC location | String | 5.415667 |
vehicleModel | The model of the Vehicle | String | PHEV |
vehicleVinNumber | Unique Vehicle Identification Number (VIN) | String | L6TBX2E68GE0145012 |
vehicleRegNumber | Registration number of the vehicle | String | 4572LST |
Business Scenario 1: Create work order for CAR delivery
Customer creates the work order for CAR delivery by entering all the mandatory details required for SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operative via mobile application and executes on the ground by the operative.
Field | Description | Data Type | Required/Optional | Examples |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
workTypeId | Indicates the type of work order | String | Required | 08q9E000000Do7yQAC |
orderNumber | Unique ID.Note: The Fleet customer creates the order number that can be used as reference | String | Required | LMB143082152176 |
jobDate | The preferred start date and end date of the job | Date format: YYYY-MM-DD | Required | 2022-12-28 11:00:00 |
Country | The country name of either the customer address or a MCC location | String | Required | France |
countryISOCode | The ISO code of the country, of the job address | String | Required | FRA |
firstName | The first name of the end customer whose the job has booked | String | Required | John |
lastName | The last name of the end customer whose the job has booked | String | Required | Smith |
customerMobile | Customer Mobile Number.Note: The service operative can use the customer mobile number to communicate and to share the job updates with them | Number | Required | 34722436539 |
mobileCountryCode | Defines the Mobile dialing code for the country | String | Required | 33 |
Note: The other fields which are not mentioned in the above table are optional to create work order for CAR delivery.
Click here to view the complete payload fields available for Create Work Order request.
Business Scenario 2: Create work order for PUD drop
Customer creates the work order for PUD drop by entering all the mandatory details required for SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operative via mobile application and executes on the ground by the operative.
Field | Description | Data Type | Required/Optional | Examples |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
workTypeId | Indicates the type of work order | String | Required | 08q9E000000Do7yQAC |
orderNumber | Unique ID.Note: The Fleet customer creates the order number that can be used as reference | String | Required | LMB143082152176 |
jobDate | The preferred start date and end date of the job | Date format: YYYY-MM-DD | Required | 2022-12-28 11:00:00 |
Country | The country name of either the customer address or a MCC location | String | Required | France |
countryISOCode | The ISO code of the country, of the job address | String | Required | FRA |
firstName | The first name of the end customer whose the job has booked | String | Required | John |
lastName | The last name of the end customer whose the job has booked | String | Required | Smith |
customerMobile | Customer Mobile Number.Note: The service operative can use the customer mobile number to communicate and to share the job updates with them | Number | Required | 34722436539 |
mobileCountryCode | Defines the Mobile dialing code for the country | String | Required | 33 |
Note: The other fields which are not mentioned in the above table are optional to create work order for PUD drop.
Click here to view the complete payload fields available for Create Work Order request.
Business Scenario 3: Create work order for PUD Pickup
Customer creates the work order for PUD Pickup by entering all the mandatory details required for SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operative via mobile application and executes on the ground by the operative.
Field | Description | Data Type | Required/Optional | Examples |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
workTypeId | Indicates the type of work order | String | Required | 08q9E000000Do7yQAC |
orderNumber | Unique ID.Note: The Fleet customer creates the order number that can be used as reference | String | Required | LMB143082152176 |
jobDate | The preferred start date and end date of the job | Date format: YYYY-MM-DD | Required | 2022-12-28 11:00:00 |
Country | The country name of either the customer address or a MCC location | String | Required | France |
countryISOCode | The ISO code of the country, of the job address | String | Required | FRA |
firstName | The first name of the end customer whose the job has booked | String | Required | John |
lastName | The last name of the end customer whose the job has booked | String | Required | Smith |
customerMobile | Customer Mobile Number.Note: The service operative can use the customer mobile number to communicate and to share the job updates with them | Number | Required | 34722436539 |
mobileCountryCode | Defines the Mobile dialing code for the country | String | Required | 33 |
Note: The other fields which are not mentioned in the above table are optional to create work order for PUD Pickup.
Click here to view the complete payload fields available for Create Work Order request.
Business Scenario 4: Create work order for Test drive
Customer creates the work order for Test drive by entering all the mandatory details required for SMS to complete the task. SMS consumes the API, optimizes the logistics, allocates the task to the operative via mobile application and executes on the ground by the operative.
Field | Description | Data Type | Required/Optional | Examples |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
workTypeId | Indicates the type of work order | String | Required | 08q9E000000Do7yQAC |
jobDate | The preferred start date and end date of the job | Date format: YYYY-MM-DD | Required | 2022-12-28 11:00:00 |
Country | The country name of either the customer address or a MCC location | String | Required | France |
countryISOCode | The ISO code of the country, of the job address | String | Required | FRA |
firstName | The first name of the end customer whose the job has booked | String | Required | John |
lastName | The last name of the end customer whose the job has booked | String | Required | Smith |
customerMobile | Customer Mobile Number.Note: The service operative can use the customer mobile number to communicate and to share the job updates with them | Number | Required | 34722436539 |
mobileCountryCode | Defines the Mobile dialing code for the country | String | Required | 33 |
Note: The other fields which are not mentioned in the above table are optional to create work order for Test drive.
Click here to view the complete payload fields available for Create Work Order request.
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"workTypeId": "08q9E000000Do7yQAC",
"orderNumber": "LMB143082152176",
"linkedWorkOrderId": "44363949",
"jobDate": "2022-12-28 08:00:00",
"contractType": "Lease",
"addInstr": "Include a welcome kit in the car",
"customer": {
"firstName": "John",
"lastName": "Smith",
"customerIdentification": "100071452",
"countryISOCode": "FRA",
"customerMobile": 34722436539,
"mobileCountryCode": 33
},
"arrayOfAddress": [
{
"subWorkTypeId": "02q9E000000Co6oRAG",
"locationId": "1309E000000DRtmQAG",
"street": "Rue du Panier",
"city": "Marseille",
"zipCode": "13001",
"country": "France",
"latitude": "43.304585",
"longitude": "5.415667",
"vehicleModel": "PHEV",
"vehicleVinNumber": "L6TBX2E68GE0145012",
"vehicleRegNumber": "4572LST"
}
]
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": [
"00011923"
],
"httpStatusCode": 201,
"Message": "Successfully created work order in back end system"
}
]
}
Sample cURL Request
curl -X POST \
https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs \
-H 'authorization: Bearer Tb5xafygCyShBVl7mGcMhvKf***' \
-H 'bypass-cache: true' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 8a6721e5-277d-585f-d2e8-df87e5d088c6' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"workTypeId": "08q9E000000Do7yQAC",
"orderNumber": "LMB143082152176",
"linkedWorkOrderId": "44363949",
"jobDate": "2022-12-28 08:00:00",
"contractType": "Lease",
"addInstr": "Include a welcome kit in the car",
"customer": {
"firstName": "John",
"lastName": "Smith",
"customerIdentification": "100071452",
"countryISOCode": "FRA",
"customerMobile": 34722436539,
"mobileCountryCode": 33
},
"arrayOfAddress": [
{
"subWorkTypeId": "02q9E000000Co6oRAG",
"locationId": "1309E000000DRtmQAG",
"street": "Rue du Panier",
"city": "Marseille",
"zipCode": "13001",
"country": "France",
"latitude": "43.304585",
"longitude": "5.415667",
"vehicleModel": "PHEV",
"vehicleVinNumber": "L6TBX2E68GE0145012",
"vehicleRegNumber": "4572LST"
}
]
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems.
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Invalid or duplicate External Reference number provided while invoking the createWorkOrder Endpoint |
|
400 | RequestId value already exist in back end system |
|
400 | Work Order creation is unsuccessful because carWshopId is not present at back end system |
|
400 | Given jobId contains empty data at the back end system |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | BAD Request The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing) |
|
401 | Unauthorized The request has not been applied because it lacks valid authentication credentials for the target resource |
|
404 | Resource Not FoundThe server cannot find the requested resource |
|
405 | Method Not AllowedThe target resource does not support this method |
|
413 | Payload too large The request entity is larger than limits defined by server |
|
415 | Unsupported Media Type The server refuses to accept the request because the payload format is in an unsupported format. |
|
429 | Too Many Requests The Request reached maximum allocated rate limit. |
|
500 | Internal Server error The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
503 | Service Unavailable The server is not ready to handle the request. Try the request again after sometime |
|
Get Job Details Service
Introduction
This API retrieves the details of the specific work order. The path-param for the unique job ID needs to be set mandatory in the end-point path-param placeholder.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | GET |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/jobs/{jobId} |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path parameters and the descriptions are given below.
Parameter | Description |
---|---|
jobId | The mandatory unique Job ID (path-param) to retrieve the details of a particular job |
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"workOrderDetails": {
"jobDate": "2022-12-28 08:00:00",
"contractType": "Lease",
"addInstr": "Include a welcome kit in the car",
"workOrderStatus": "Pending slot confirmation",
"scheduledSlot": "11:00 - 12:00",
"customer": {
"firstName": "John",
"lastName": "Smith",
"customerIdentification": "100071452",
"countryISOCode": "FRA",
"customerMobile": 34722436539,
"mobileCountryCode": 33
},
"arrayOfAddress": [
"addressType": "Pickup the vehicle",
"street": "Rue du Panier",
"city": "Marseille",
"zipCode": "13001",
"country": "France",
"latitude": "43.304585",
"longitude": "5.415667",
"vehicleModel": "PHEV",
"vehicleVinNumber": "L6TBX2E68GE0145012",
"vehicleRegNumber": "4572LST"
]
},
"linkedWorkOrderDetails": [
{
"workOrderId": "44363949",
"jobDate": "2022-12-28 08:00:00",
"contractType": "Lease",
"addInstr": "Include a welcome kit in the car",
"workOrderStatus": "Pending slot confirmation",
"scheduledSlot": "11:00 - 12:00",
"customer": {
"firstName": "John",
"lastName": "Smith",
"customerIdentification": "100071452",
"countryISOCode": "FRA",
"customerMobile": 34722436539,
"mobileCountryCode": 33
},
"arrayOfAddress": [
"addressType": "Pickup the vehicle",
"street": "Rue du Panier",
"city": "Marseille",
"zipCode": "13001",
"country": "France",
"latitude": "43.304585",
"longitude": "5.415667",
"vehicleModel": "PHEV",
"vehicleVinNumber": "L6TBX2E68GE0145012",
"vehicleRegNumber": "4572LST"
]
}
]
}
]
}
Sample cURL Request
curl -X GET \
https://api-uat.shell.com/mobility-systems-workorder-api/api/jobs/00092801 \
-H 'authorization: Bearer *****' \
-H 'cache-control: no-cache' \
-H 'postman-token: 350fd5b7-2a5d-8281-aab2-28d3a90d3543' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the Error thrown by back end system due to business validation or invalid input data or Error due to sub systems.
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Bad RequestGiven jobId contains empty data at the back end system |
|
400 | Bad RequestThe External Reference Number is already used. Please enter unique External Reference Number |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Get Job Details Service API.
Update Customer Details Service
Introduction
Once the Work Order is created, customer can use the endpoint to update customer details.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | PUT |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/jobs/{jobId}/customer |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Content-Type | This is to indicate the media type of the resource i.e., application/json |
Authorization | Bearer access_token (Access Token generated from the OAuth end point) |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path Parameter and the description are given below.
Parameter | Description |
---|---|
jobId | The mandatory unique Job ID (path-param) to retrieve the details of a particular job |
The request body has the below mentioned data to Update Customer Details Service.
Field | Description | Data Type | Required/Optional | Example |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
fisrtName | The first name of the end customer whose the job has booked | String | Required | John |
lastName | The last name of the end customer whose the job has booked | String | Required | Doe |
custMobile | Customer mobile number is used by the service operative to communicate and to share the job updates with the customer | Number | Required | 56272891 |
custId | Government approved customer identification that can be used to authenticate the customer | String | Required | License Number: 123 456 789 |
addInstr | Any other additional instruction.Note: Fleet customer provides any additional instructions required for the service operative to know and to exceute the task | String | Optional | Get documents signed |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"custId": "123445",
"fisrtName": "John",
"lastName": "Doe",
"custMobile": "56728910",
"custEmail": "john.doe@gmail.com",
"addInstr": "Include a welcome kit in the car"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": "00011810",
"httpStatusCode": 200,
"Message": "Customer value successfully updated in Back End System"
}
]
}
Sample cURL Request
curl -X PUT \
https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012707/customer \
-H 'authorization: Bearer 32axZ6RPVHr5JwSOZahGiDqGTeGU' \
-H 'bypass-cache: true' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: f96d1f23-f64c-dfa6-7c12-c9878aefce95' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"custId": "123445",
"fisrtName": "John",
"lastName": "Doe",
"custMobile": "56728910",
"custEmail": "john.doe@gmail.com",
"addInstr": "Include a welcome kit in the car"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or Error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | WorkOrder is Confirmed, so you cannot update the customer details |
|
400 | Work Order does not exist |
|
400 | WorkOrder is Canceled, so you cannot update the customer details |
|
400 | WorkOrder is Completed, so you cannot update the customer details |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Update Customer Details Service API.
Update Vehicle Details for Specific Work Orders
Introduction
Updation of vehicle details pertaining to a particular job
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | PUT |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/jobs/{jobId}/vehicle |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth end point) |
Content-Type | This is to indicate the media type of the resource i.e., application/json |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path Parameter and the description are given below.
Parameter | Description |
---|---|
jobId | The mandatory unique Job ID (path-param) to retrieve the details of a particular job |
The request body has the below mentioned data to Update Vehicle Details for Specific Work Orders.
Field | Description | Data Type | Required/Optional | Example |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
isCarReady | Is the vehicle ready for the job | String | Required | Yes |
carVin | The Vehicle Identification Number of the vehicle | String | Required | 4T1BF1FK4CU609641 |
carModel | The corresponding vehicle model | String | Required | 01 |
carReg | The vehicle registration number | String | Required | J 206 FV |
subworkTypeId | ID of the subwork Type | String | Required | 1234 |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"isCarReady": true,
"carVin": "4T1BF1FK4CU609641",
"carModel": "Model 1",
"carReg": "J 206 FV",
"subworkTypeId": "1234"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": "00011810",
"httpStatusCode": 200,
"Message": "Successfully updated vehicle value in Back End System"
}
]
}
Sample cURL Request
curl -X PUT \
https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012765/vehicle \
-H 'authorization: Bearer cJhZbUVWqLVeWP7m2rMdGqpInhjQ' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-H 'postman-token: 45fb1bb9-04a8-87fe-65a7-196e512e01de' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"isCarReady": true,
"carVin": "4T1BF1FK4CU609641",
"carModel": "Model 1",
"carReg": "J 206 FV",
"subworkTypeId": "1234"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Work Order is confirmed, so you cannot update the vehicle details |
|
400 | Work Order does not exist |
|
400 | Work Order is canceled, so you cannot update the vehicle details |
|
400 | workOrder is Completed, so you cannot update the vehicle details |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Update Vehicle Details for Specific Work Orders API.
Cancel Job Service
Introduction
The two purpose of this API are:
- Manual cancellation: If the Work Order is created and not required further, then the Work Order will be cancelled manually using this API
- Automatic Cancellation by System: If no slot is confirmed for a Work Order, then system will trigger this API to automatically cancel the Work Order a day prior to the service commencement date.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | PUT |
URI | https://api0-uat.shell.com/mobility-systems-workorder-api/api/jobs/{jobId}/cancel |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
Content-Type | This is to indicate the media type of the resource i.e., application/json |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path Parameter and the description are given below.
Parameter | Description |
---|---|
jobId | The mandatory unique Job ID (path-param) to retrieve the details of a particular job |
The request body has the below mentioned data to Cancel Job Service.
Field | Description | Data Type | Required/Optional | Example |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
statusReasonCode | Status reason code to cancel the job | String | Required | Cancelled by EC staff |
statusReason | Status reason to cancel the job | String | Required | Customer did not show up |
otherReason | Any other reason for cancellation | String | Optional |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"statusReasonCode": "Cancel-012",
"statusReason": "Customer requested cancelation"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": "00011810",
"httpStatusCode": 200,
"Message": "Successfully updated Cancel value in Back End System"
}
]
}
Sample cURL Request
curl -X PUT \
https://api-dev.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012708/cancel \
-H 'authorization: Bearer iDOUgTzmNFfuBH6LrZcoykgfpnK1' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: ac6b5721-514d-c494-2313-837e1b9ae5de' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"statusReasonCode": "Cancel-012",
"statusReason": "Customer requested cancelation"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Unable to cancel the workorder because of invalid JobId in the request |
|
400 | Not able to cancel the workorder for invaild StatusResonse code standarded. Example : 1 : "1 - Cancelled by Business", 2 : "2 - Cancelled by Operative", 3 : "3 - System cancels the Work Order (Auto Cancel)", 4 : "4 - Cancelled by Shell/Logistics Manager" |
|
400 | Not able to cancel the workorder for the StatusReason. i.e status reason is invalid |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Cancel Job Service API.
Book Slot Service
Introduction
Once the work order is created, this API will display list of available slots to the user.
- User will have the ease to select the available slot as per their preference for pickup/drop
- User will have the ease to select/change the date as per their convenience
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | PUT |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012707/slotBooking |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth end point) |
Content-Type | This is to indicate the media type of the resource i.e., application/json |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The request body has the below mentioned data to book the slot for Job Service.
Field | Description | Data Type | Required/Optional | Notes |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
slotTime | Time slot to book the work order | String | Required | 10:00 - 11:00 |
jobDate | Date Slot to book the work order | DateTime | Required | 9/20/2022 |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"slotTime": "13:00 - 14:00",
"jobDate": "2022-12-28 08:00:00"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": "00011810",
"httpStatusCode": 200,
"Message": "Successfully updated SlotBooking value in Back End System"
}
]
}
Sample cURL Request
curl -X PUT \
https://api01-uat.shell.com/mobility-systems-workorder-api/api/slotBooking \
-H 'authorization: Bearer ******' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 705950c6-b2f3-ac50-5d22-f974fe674e9f' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"slotTime": "13:00 - 14:00",
"jobDate": "2022-12-28 08:00:00"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Not able to update the slot for WorkOrder does not exist in system |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Book Slot Service API.
Schedule Work Order Service
Introduction
Once the Work Order is created, the system will trigger the endpoint to update work ordera' start and end date.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | PUT |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012788/woSchedule |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
Content-Type | This is to indicate the media type of the resource i.e., application/json |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The request body has the below mentioned data to Schedule Work Order Service.
Field | Description | Data Type | Required/Optional | Example |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
jobStart | New Start-date for the workorder | DateTime | Required | 2022-02-28T09:00:00.000Z |
jobEnd | New End-date for the workorder | DateTime | Required | 2022-02-28T09:00:00.000Z |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"jobStart": "2022-02-28T09:00:00.000Z",
"jobEnd": "2022-02-28T18:00:00.000Z"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"JobId": "00092668",
"Message": "Detailed information about the response"
}
]
}
Sample cURL Request
curl -X PUT \
https://api-uat.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012788/woSchedule \
-H 'authorization: Bearer abpOGTZneIhGQ9BLi6tDVZmH8ymz' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: ed1378f7-a000-e1c6-a7b9-7246687c33d5' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"jobStart": "2022-02-28T09:00:00.000Z",
"jobEnd": "2022-02-28T18:00:00.000Z"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | WorkOrder does not exist in system or is not associated with this customer |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Schedule Work Order Service API.
Reschedule Work Order Date Service
Introduction
Once the work order is created, System will trigger the endpoint to Reschedule the work order.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | POST |
URI | https://api-dev.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012788/woReschedule |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
Content-Type | This is to indicate the media type of the resource i.e., application/json |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The request body has the below mentioned data to reschedule Work Order Date Service.
Field | Description | Data Type | Required/Optional | Example |
---|---|---|---|---|
accountId | Unique account ID required to identify the customer | String | Required | 0019E00001jzZFQQA2 |
reScheduleDate | New date to reschedule the work order | DateTime | Required | 2020-12-28 08:00:00 |
Sample Request Body
[
{
"accountId": "0019E00001jzZFQQA2",
"reScheduleDate": "2022-02-28T09:00:00.000Z"
}
]
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"accountId": "0019E00001jzZFQQA2",
"JobId": "00011810",
"Message": "WorkOrder Reschedule is sucessfull."
}
]
}
Sample cURL Request
curl -X PUT \
https://api-dev.shell.com/mobility-systems-workorder-api/v1/api/jobs/00012788/woReschedule \
-H 'authorization: Bearer vnnv3EqytDAKUeyi4fA2HAimq3wY' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: e39f9e84-5dfc-614e-81ac-8aa6ad65d51f' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-d '[
{
"accountId": "0019E00001jzZFQQA2",
"reScheduleDate": "2022-02-28T09:00:00.000Z"
}
]'
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the errors thrown by back end system due to business validation or invalid input data or error due to sub systems
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Rescheduling with Invalid Work Order Number |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Reschedule Work Order Date Service API.
Get Location Details
Introduction
This API provides the location detials of the specific customer account. The path-param for the unique account ID needs to be set mandatory in the end-point path-param placeholder.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | GET |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/accounts/{accountId}/locations |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path parameters and the descriptions are given below.
Parameter | Description |
---|---|
accountId | The mandatory unique account ID (path-param) to retrieve the location details for the specific customer account |
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"country": "Paris",
"Territories": [
{
"territory": "Paris North",
"Addresses": [
{
"address": "Paris Parking grounds",
"addressID": "1309E000000DRv7QAG"
}
]
}
]
}
]
}
Sample cURL Request
curl -X GET \
https://api-dev.shell.com/mobility-systems-workorder-api/v1/api/accounts/0019E00001jzZFQQA2/locations \
-H 'authorization: Bearer a67mH3Q8K5kjvyqBZ9qDaGEcAD3n' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-H 'postman-token: 8cfdfc54-d9c5-68bd-c537-f835e16d01c4' \
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the Error thrown by back end system due to business validation or invalid input data or Error due to sub systems.
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Bad RequestGiven accountId contains empty data at the back end system |
|
400 | Bad RequestThe External Reference Number is already used. Please enter unique External Reference Number |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Get Location Details API.
Get Work Order and Sub Work Order Type Details
Introduction
This API provides the details of the work order and sub work order types of the specific customer account. The path-param for the unique account ID needs to be set mandatory in the end-point path-param placeholder.
The end-to-end process is illustrated in the sequence diagram given below.
Key Request Parameters
The key request parameters are:
Element | Value |
---|---|
Method | GET |
URI | https://api-uat.shell.com/mobility-systems-workorder-api/api/accounts/{accountId}/workTypes |
The Header names and the descriptions are given below.
Header Name | Description |
---|---|
Authorization | Bearer access_token (Access Token generated from the OAuth 2.0 end point) |
RequestId | RequestId must be unique identifier value that can be used by the consumer to correlate each request/response. Format. In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens). |
The Path parameters and the descriptions are given below.
Parameter | Description |
---|---|
accountId | The mandatory unique account ID (path-param) to retrieve the work order and sub work order types for the specific customer account |
Sample Response Body
{
"requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
"status": "SUCCESS",
"data": [
{
"WorkTypeName": "Car Delivery",
"workTypeId": "08q9E000000Do7oQAC",
"subWorkTypes": [
{
"subWorkTypeName": "pickupAddress",
"subWorkTypeId": "08q9E000000Do8oQAC"
}
],
"fields": [
{
"fieldName": "JobId",
"dataType": "string",
"isMandatory": "true"
}
]
}
]
}```
### Sample cURL Request
```Curl
curl -X GET \
https://api-dev.shell.com/mobility-systems-workorder-api/v1/api/accounts/0019E00001jzZFQQA2/workTypes \
-H 'authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImlQYWFzXzEiLCJwaS5hdG0iOiI1cXNqIn0.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6IkhndkJ0QmIwRUVheE9MNTVhZlh4dHEwV1Q5VEVHcjVFIiwiaXNzIjoiaHR0cHM6Ly9zc28tZGV2LnNoZWxsLmNvbSIsIm5iZiI6MTY1NzU0Njc4MCwiT3JnTmFtZSI6IlNIRUxMLkNPTSIsImlhdCI6MTY1NzU0NjY2MCwiZXhwIjoxNjU3NTQ3NjgwfQ.ErTQw2773DkBn8c5xqHWzoSHcNFyVop9h_j1-bWJ2WREHSNwumM4ht9PoyTA4zlBRFhykGrqzAlbVjUFPwQuMElUcLpZC1GmYVuTbA-eLRwmo-DpksQoeohY68yCoHZipWGn2GcbhWIyAkHYVj4N3yXnZbny57HsDolHGwarv57EtzdTsQ8hnefXMg36duJ58YfBr6YDMz_ZBIiQohauXbhVGfTZFwb4qOa3Xfdjdy7GK8LmlW8cXpVw93qq4g9eu-60FVlDDFZfZOi6-h4Ct-AeDMFrECShigaswsg-qzfBugTOCqKQLopL9osLR08o5APe9QdpYLsXqhHru40SdA' \
-H 'cache-control: no-cache' \
-H 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
-H 'postman-token: 14b4778d-a100-f424-f60b-38705575e3cd' \
Exception Handling
The two main types of the exceptional scenario errors to create work order service are:
- Application/ Business Error
- Common Gateway Errors
Application/Business Errors
Application/Business Errors are the Error thrown by back end system due to business validation or invalid input data or Error due to sub systems.
HTTP Status Code | Error Scenario | Error Response |
---|---|---|
400 | Bad RequestGiven accountId contains empty data at the back end system |
|
400 | Bad RequestThe External Reference Number is already used. Please enter unique External Reference Number |
|
Common Gateway Errors
Common Gateway Errors handle the errors like invalid token, missing mandatory parameters or due to missing or invalid content type. Gateway handles these common errors across all APIs.
Click here for more details of common errors on Get Work Order and Sub Work Order Type Details API.