Getting Started with Toll Lookup APIs
This section describe endpoints related to implementation and configuration of master data from eTM system.
Shell eTM lookups API product provides seamless operations like fetching master configuration data like country type, vehicle category type, emission type, fuel type, vehicle type, vehicle model type, trailer type, and emission type.
This API product consists of single endpoint helps to fetch various lookup categories.
API End Point - https://host-name/fleetmanagement/v1/master/lookups
- Country Types
- Vehicle Category Types
- Emission Typse
- Fuel Types
- Vehicle Types
- Vehicle Model Types
The API is protected with basic authentication method.
Authentication
Shell API’s are secured by basic authentication plus API key. It uses the Base64 encoded Client ID and Client Secret in the Authorization header and apikey header. The end-to-end process is illustrated in the sequence diagram below.
sequenceDiagram
participant Partner Application
participant Shell
alt [Call Functional Endpoint]
Partner Application->>Shell: [1] Initiate request to functional endpoint with the basic authentication (Parsing the Base64 encoded Client ID and Client Secret) plus apikey header
Shell->>Partner Application: [2] Returns a response
end
Key Request Parameters
After receiving the Client ID and Client Secret, the next step is to make an API request using Basic authentication. This request contains an apikey header and Authorization header in the form of: Basic (credentials), where the credentials is the Base64 encoding of Client ID and Client Secret.
Following are the key parameters:
- Method: POST
- URL: https://host-name/fleetmanagement/v1/master/lookups
- Authentication Type: Basic authentication (Client ID and Client Secret)
- apikey: Header (Client ID)
Exception Handling
| HTTP Code | Description | Scenarios |
|---|---|---|
| 400 | Bad Request | If invalid parameter value passed |
| 401 | Unauthorized | If invalid User Token passed |
| 403 | Unauthorized | If invalid API key passed |
| If the operation is accessible only to ‘Shell Administrator’ or ‘Service Account’ | ||
| If logged in user does not have access to requested ColCoId/ColCoCode | ||
| 504 | Not Found | If requested item does not exist |
| 500 | Internal Server Error | Fault String |
Sample Exception Structure
{
"fault": {
"faultstring": "Raising fault. Fault name : RaiseFaultAuthorizationCheck",
"detail": {
"errorcode": "steps.raisefault.RaiseFault"
}
}
}
Vehicle Category Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMrpkIThellog==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUohello6rpkc' \
--data-raw '{
"colCoCode": 14,
"ConfigurationItems":["VehicleCategoryTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "0c789a3b-d14b-4bd4-d4f4-fde28849094a",
"VehicleCategoryTypes": [
{
"name": "M1",
"longName": "People transportation M1",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of passengers and comprising no more than eight seats in addition to the driver's seat.",
"id": "000fa969-989e-4cbb-92e6-014d6b49ada9"
},
{
"name": "N3",
"longName": "Heavy Goods Vehicle N3",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of goods and having a maximum mass exceeding 12 tonnes. ",
"id": "af4b3f75-bb8e-4416-8fb8-44e3d69966a8"
},
{
"name": "N2",
"longName": "Heavy Goods Vehicle N2",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of goods and having a maximum mass exceeding 3,5 tonnes but not exceeding 12 tonnes.",
"id": "d222056b-4834-4c6d-b9fc-503810eff4bd"
},
{
"name": "M2",
"longName": "People transportation M2",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of passengers, comprising more than eight seats in addition to the driver's seat, and having a maximum mass not exceeding 5 tonnes. ",
"id": "c4d63872-27a1-47d4-b04f-a049457688a4"
},
{
"name": "M3",
"longName": "People transportation M3",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of passengers, comprising more than eight seats in addition to the driver's seat, and having a maximum mass exceeding 5 tonnes.",
"id": "00c7d154-9305-4d79-ad0c-b8bda9acd734"
},
{
"name": "N1",
"longName": "Heavy Goods Vehicle N1",
"code": "00024",
"description": "Vehicles designed and constructed for the carriage of goods and having a maximum mass not exceeding 3,5 tonnes. ",
"id": "9cfd89af-9367-4bae-b8ab-e2d5e380b128"
}
]
}Country Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZrpkIThello1MxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZhelrpkIRc' \
--data-raw '{
"colCoCode": 14,
"ConfigurationItems":["CountryTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "eb1ebac2-034c-4294-b202-faabcea88484",
"CountryTypes": [
{
"name": "Moldova",
"a1": "MD",
"a2": "MD",
"id": "b5efe6e0-4f6a-4201-ba4f-05d2a78f639a"
},
{
"name": "Andorra",
"a1": "AND",
"a2": "AD",
"id": "5949c0d3-3676-4b2b-8090-07b507038cac"
},
{
"name": "France",
"a1": "F",
"a2": "FR",
"id": "088de29a-b84e-4753-9d25-174a5ac777da"
},
{
"name": "Switzerland",
"a1": "CH",
"a2": "CH",
"id": "ca6801c7-3044-4b90-b92b-20bad6f2e78a"
},
{
"name": "Poland",
"a1": "PL",
"a2": "PL",
"id": "b345cf2a-6a3f-4d2e-a719-22e2817b3f08"
},
{
"name": "Greece",
"a1": "GR",
"a2": "GR",
"id": "93929b56-bc7a-43a9-aa3c-24574479b291"
},
{
"name": "Italy",
"a1": "I",
"a2": "IT",
"id": "7f50cb6e-aecb-4870-90c4-fcb8799ee539"
},
]
}Vehicle Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMRVM3TrpkIMxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZMN6JrpkIRc' \
--data-raw '{
"colCoCode": 14,
"ConfigurationItems":["VehicleTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "354f14ab-cc06-4f7d-dbe5-9258ac28a9d1",
"VehicleTypes": [
{
"name": "PL",
"longName": "HGV",
"id": "77307014-a0e1-49fd-8468-128e00f13ce6"
},
{
"name": "VL",
"longName": "LGV",
"id": "fb7ef715-1f00-49b4-b856-e879f44286db"
}
]
}Emission Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdrpkIVMhelloHR1MxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKhelloVZMNrpkIpqRc' \
--data-raw '{
"RequestId": "581101d3-6658-414d-9e34-03d53c2f3786",
"colCoCode": 14,
"ConfigurationItems":["EmissionTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "581101d3-6658-414d-9e34-03d53c2f3786",
"EmissionTypes": [
{
"class": "05",
"name": "Euro 5",
"id": "676354c7-1369-4875-b7f9-707ef651bb83"
},
{
"class": "09",
"name": "EEV",
"id": "e598ddfd-c19d-4ea2-ac77-931095c4c888"
},
{
"class": "01",
"name": "Euro 1",
"id": "5c1ebec5-1af3-4f2e-b85a-95505cab2a07"
},
{
"class": "04",
"name": "Euro 4",
"id": "8025565b-b87f-4146-9bdb-b1c871c0177d"
},
{
"class": "00",
"name": "Euro 0",
"id": "552e016c-8fe5-468d-a8c0-c611a5b31583"
},
{
"class": "03",
"name": "Euro 3",
"id": "1818805c-5322-4f60-8075-e8aba63e0754"
},
{
"class": "02",
"name": "Euro 2",
"id": "8b2562f3-09d5-4b21-8747-ea41e11bc2c6"
},
{
"class": "06",
"name": "Euro 6",
"id": "4ed21b63-ebdd-4617-a204-fbcf6fe1194f"
}
]
}Fuel Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5Xdlhello3T3NrpkIxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZhelloKrpkIc' \
--data-raw '{
"colCoCode": 14,
"ConfigurationItems":["FuelTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "1df5fd00-5c6d-4ede-c08a-c7c4c504bda3",
"FuelTypes": [
{
"fuelShort": "EL",
"fuelName": "Electricity",
"id": "84a31056-f338-4bb6-b15e-0425ef10037a"
},
{
"fuelShort": "GN",
"fuelName": "Natural Gas",
"id": "4eaf4381-23fa-438d-a7b6-0bd5ae043f91"
},
{
"fuelShort": "EE",
"fuelName": "Hybrid Gasoline-Electric",
"id": "13453677-c4c1-4059-853c-131dc25ba08b"
},
{
"fuelShort": "GO",
"fuelName": "Diesel",
"id": "6cf0e140-36e6-4dc7-844f-20916eba1a2c"
},
{
"fuelShort": "GA",
"fuelName": "Wood Gas",
"id": "e34ccd33-f9b2-4f48-a8ff-2f46748b241f"
},
{
"fuelShort": "GG",
"fuelName": "Hybrid wood gas-diesel",
"id": "49aeaa56-02b8-4f73-8f99-3120ee742207"
},
{
"fuelShort": "94",
"fuelName": "Liquefied Natural Gas (LNG)",
"id": "69f7574a-4a7c-4767-9e06-4ee8e5617967"
},
{
"fuelShort": "FE",
"fuelName": "Super-ethanol",
"id": "b174f096-93ba-44ae-a44a-57e31f3a21fd"
},
{
"fuelShort": "EG",
"fuelName": "Hybrid Gasoline-LGP",
"id": "400e3371-e4eb-4075-9ab7-8adb7fc71a47"
},
{
"fuelShort": "EN",
"fuelName": "Hybrid Gasoline-Natural Gas",
"id": "bf58dd71-0b7c-443f-8d57-fee15df270cc"
}
]
}Vehicle Model Type
Sample Request
curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/master/lookups' \
--header 'content-type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OUhelloM3TrpkIMxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0hello6JKrpKiRc' \
--data-raw '{
"colCoCode": 14,
"ConfigurationItems":["VehicleModelTypes"]
}'Sample Response
{
"ConfigurationItems": null,
"RequestorAppId": 0,
"Error": {
"Code": "0000",
"Description": "Success."
},
"RequestId": "3886a3f0-f46c-4cfb-bca8-24f3314625fd",
"VehicleModelTypes": [
{
"name": "CATERPILLAR",
"id": "d0410374-65fc-467e-bc87-086ffa9a8d52"
},
{
"name": "TATRA",
"id": "5f48b7cb-1c7a-4c37-a2e6-13bad1b04de5"
},
{
"name": "FERRARI",
"id": "c0a76af8-d8d9-4987-8640-15da32ea3a6d"
},
{
"name": "STAR",
"id": "476af16a-538a-41f8-bd65-1d8c0d35aa10"
},
{
"name": "TEREX",
"id": "7a423770-838a-4879-b731-1db938919b93"
},
{
"name": "INTERNATIONAL",
"id": "ea199bc1-2a66-44dc-a91f-1ff71130ae63"
},
{
"name": "AUDI",
"id": "2d60ac17-759e-4c1f-8bbf-24bdcdb553d5"
},
{
"name": "ETWO",
"id": "93c6671e-3dc4-46e0-9c37-24d8d6d80ba9"
},
{
"name": "VOLKSWAGEN",
"id": "286a717b-b4af-4225-8878-304f9df3f2ed"
},
{
"name": "PRAGA",
"id": "c82f5379-bbc8-41d8-905b-7e9f3f9d2b2d"
},
{
"name": "SUZUKI",
"id": "be5b049e-0671-4f09-bb80-fe6eeca8a80d"
}
]
}