Getting Started with On Board Unit (OBU) Management APIs

This section describe endpoints related to implementation and configuration of Toll Order and OBU Transfer Requests.
Shell eTM OBU API product provides seamless operations like creating and searching with respect to OBU Management for API consumers.

This API product consists of four endpoints which can be used in order to develop different user journeys.

API End Point	API Functionality
/fleetmanagement/v3/tollorder/create	This endpoint will create the toll order by request object.
/fleetmanagement/v2/tollorder/search	This endpoint will get the order requests for specific collection of vehicles.
/fleetmanagement/v1/tollobutransfer/create	This endpoint will create the OBU Transfer Request by request object.
/fleetmanagement/v1/tollobutransfer/search	This endpoint will get the OBU Transfer Requests by customer and optional filters.

All the APIs are 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 receive 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
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 parameter value passed
403	The request is valid and server is refusing action	If invalid parameter value passed
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"
        }
    }
}

Toll Order

Create

Key Request Parameters

Method: POST
URL: https://host-name/test/fleetmanagement/v3/tollorder/create
Authentication Type: Basic authentication (Client ID and Client Secret)
apikey: Header (Client ID)

Sample Request

curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v3/tollorder/create' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMRVM3T3NHR1rpk==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZMN6JKrpk' \
--data-raw '{
    "ColcoId": 14,
    "ColcoCode": 14,
    "ContactEmail": "lon-sc-fleethub-notifications-uat@shell.com",
    "vehicles": [
        {
            "vehicleId": "1f42b4c7-1044-4067-ad9d-f6a3f55cdf28",
            "devices": [
                {
                    "deviceTypeId": "efcd57be-c12e-416e-84f7-2041367b4268",
                    "deviceStateId": "9e568cf0-0fac-4553-ac00-4ba4b93329e1",
                    "services": [
                        {
                            "serviceId": "bc5c7ae4-5f59-412a-8fce-20d6b64b170b",
                            "operationTypeId": "80f8bf37-98d9-4d69-b30c-1c41488c2e8e",
                            "validFrom": "2022-11-17T00:00:00",
                            "validTo": "2022-12-17T00:00:00",
                            "trailerAxlesNumber": 8
                        }
                    ],
                    "documents": [],
                    "isAutorenewalEnabled": false
                }
            ],
            "accountNumber": "DE00000008"
        }
    ],
    "deliveryAddress": {
        "title": "Mr",
        "firstName": "FIRSTName1",
        "lastName": "lastName1",
        "companyName": "Test1",
        "addressLine1": "TestLine11",
        "addressLine2": "TestLine21",
        "addressLine3": "TestLine31",
        "zip": "88040",
        "city": "FRIEDRICHSHAFEN",
        "countryTypeId": "a0e495ce-9c39-42f2-92bb-d9aa3e416821",
        "dhlZipCodeId": "0705d1db-0006-42c6-9683-b10b16dc000f",
        "italianProvinceId": ""
    },
    "userName": "8ab70c88-4499-41c8-a98a-d6d58230b47b",
    "ColCoId": 14,
    "ColCoCode": 14,
    "payerNumber": "DE00000008"
}'

Sample Response

{
    "requestOrderId": "6e231a5c-5f92-ed11-ac20-14cb65652125",
    "requestId": "381dbd98-aa21-4efe-d010-1b7d4b689009",
    "error": {
        "code": "0000",
        "description": "Success"
    }
}

Search

Key Request Parameters

Method: POST
URL: https://host-name/test/fleetmanagement/v3/tollorder/search
Authentication Type: Basic authentication (Client ID and Client Secret)
apikey: Header (Client ID)

Sample Request

curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v2/vehicle/search' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMRVM3T3NHR1rpk==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZMN6Jrpkic' \
--data-raw ' {
        "CountryAccess": null,
        "PageSize": 200,
        "CurrentPage": 1,
        "SortOptions": [
            {
                "Member": "licensePlate",
                "SortType": 2
            }
        ],
        "Filters": [

            {
                "Member": "status",
                "Operator": 2,
                "Value": "active"
            }
        ],
        "userName": "8ab70c88-4499-41c8-a98a-d6d58230b47b",
        "ColCoId": 14,
        "ColCoCode": 14,
        "payerId": 9,
        "payerNumber": "DE00000008",
        "accountNumber": "DE00000008"
    }
'

Sample Response

{
    "activeCount": 59,
    "accessRestrictedCount": 1137,
    "emptyCount": 789,
    "softDeletedCount": 0,
    "rowCount": 59,
    "currentPage": 1,
    "totalPages": 59,
    "entities": [
        {
            "licensePlate": "YU 131ST",
            "countryTypeId": "7f50cb6e-aecb-4870-90c4-fcb8799ee539",
            "grossVehicleWeightRating": 2500.0,
            "authorizedGrossVehicleWeight": 3000.0,
            "totalVehicleWeight": 2000.00,
            "truckTractorAxlesNumber": 3,
            "trailerAxlesNumber": 2,
            "emissionTypeId": "e598ddfd-c19d-4ea2-ac77-931095c4c888",
            "emissionTypeName": "EEV",
            "emissionTypeClass": "09",
            "fuelTypeId": "07bab06c-406b-4fcc-8855-d2d193157932",
            "fuelTypeName": "Gasoline",
            "vehicleCategoryTypeId": "9cfd89af-9367-4bae-b8ab-e2d5e380b128",
            "vehicleCategoryTypeLongName": "Heavy Goods Vehicle N1",
            "vehicleTypeId": "fb7ef715-1f00-49b4-b856-e879f44286db",
            "vehicleTypeLongName": "LGV",
            "firstDayOfRegistration": "1997-09-08T00:00:00",
            "accountNumber": "DE00000008",
            "eTMCustomerId": "169f678e-d5df-4963-a3cf-71985fbc2f9f",
            "status": "Active",
            "vehicleModelTypeId": "2d60ac17-759e-4c1f-8bbf-24bdcdb553d5",
            "height": 8756,
            "trailerTypeId": "52670d54-ecd1-4db7-8424-0313cff23d7e",
            "trailerMaxLadenWeight": 0,
            "trailerWeightUnladen": 0,
            "vin": "1G1ZC5E08CF148007",
            "lpnTypeId": "7546d6b3-7dc7-4464-b027-947600eb7158",
            "lpnTypeName": "Plate number of vehicle held for another purpose",
            "lpnTypeNote": "text test",
            "hasCompleteData": true,
            "devices": [
                {
                    "status": "Active",
                    "deviceId": "6670c6ce-1bcf-467b-9ef8-33d3f7648ac5",
                    "deviceTypeId": "776e37a8-d39f-4c0e-9fcd-256732e03edb",
                    "obuNumber": "1234567890",
                    "services": [
                        {
                            "status": "Deactivated",
                            "serviceId": "5f4aeebd-f042-4e96-9c93-0cd832f0358b",
                            "serviceName": "Toll4Europe Austria road",
                            "isSupportedAtSfh": true,
                            "isSupportedAtSfhForPreRegistration": false,
                            "countries": [
                                {
                                    "name": "Austria",
                                    "a1": "A",
                                    "a2": "AT",
                                    "id": "fb94f920-e80b-460d-8841-bb64adce80ac"
                                }
                            ]
                        },
                        {
                            "status": "Active",
                            "serviceId": "42699d7d-0aaa-419b-a515-d06bcb5ec5ba",
                            "serviceName": "Toll4Europe Slovenia",
                            "isSupportedAtSfh": false,
                            "isSupportedAtSfhForPreRegistration": true,
                            "countries": [
                                {
                                    "name": "Slovenia",
                                    "a1": "SLO",
                                    "a2": "SI",
                                    "id": "683f9aa9-5a4f-40f9-a645-ee6bf4eb543e"
                                }
                            ]
                        },
                {
                    "status": "Active",
                    "deviceTypeId": "d9ac2f11-42b9-47cd-be57-096618687b65",
                    "services": [
                        {
                            "status": "Active",
                            "serviceId": "940110a6-1117-45a6-a988-58c5a5948c2e",
                            "serviceName": "FDE Frejus tunnel",
                            "isSupportedAtSfh": true,
                            "isSupportedAtSfhForPreRegistration": false,
                            "countries": [
                                {
                                    "name": "France",
                                    "a1": "F",
                                    "a2": "FR",
                                    "id": "088de29a-b84e-4753-9d25-174a5ac777da"
                                },
                                {
                                    "name": "Italy",
                                    "a1": "I",
                                    "a2": "IT",
                                    "id": "7f50cb6e-aecb-4870-90c4-fcb8799ee539"
                                }
                            ]
                        }
                    ]
                }
            ],
            "countryAccess": [
                {
                    "name": "Austria",
                    "a1": "A",
                    "a2": "AT",
                    "status": "Not active",
                    "id": "fb94f920-e80b-460d-8841-bb64adce80ac"
                },
                {
                    "name": "Belgium",
                    "a1": "B",
                    "a2": "BE",
                    "status": "Not active",
                    "id": "2dfb93b4-027e-4ae4-aa03-3e7138af0223"
                },
                {
                    "name": "Italy",
                    "a1": "I",
                    "a2": "IT",
                    "status": "Active",
                    "id": "7f50cb6e-aecb-4870-90c4-fcb8799ee539"
                },
                {
                    "name": "Norway",
                    "a1": "N",
                    "a2": "NO",
                    "status": "Active",
                    "id": "9696ac0b-b78a-4c41-b9d4-358ab439889f"
                }
            ],
            "vehicleCards": [],
            "id": "9eae4f8a-8ae8-4f88-80a2-74c487d9844c"
        }
    ],
    "requestId": "87f3cf39-f3ce-4cbd-ab34-0587f23f314a",
    "error": {
        "code": "0000",
        "description": "Success"
    }
}

Toll OBU Transfer Request

Create

Key Request Parameters

Method: POST
URL: https://host-name/test/fleetmanagement/v1/tollobutransfer/create
Authentication Type: Basic authentication (Client ID and Client Secret)
apikey: Header (Client ID)

Sample Request

curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/tollobutransfer/create' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMRVM3T3NHR1MxZg==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZMN6JKpqRc' \
--data-raw '{
  "colCoCode": 32,
  "accountNumber": "CZ00001528",
  "payerNumber": "CZ00001528",
  "sortOptions": [{ "member" : "ProcessStatus" , "sortType" : 2}],
  "filters": [{ "member" : "Status" , "operator" : 2, "value" : "Active" }],
  "ObuId": "a544dbe6-3e81-4ece-bf42-96906dec3d6d",
  "VehicleId": "cf651180-fa00-462f-9c42-8d3177fbdbdf"
}'

Sample Response

{
    "obuTransferRequestId": "de1ea7bb-86a0-ed11-9174-a88c3ed9e2fe",
    "requestId": "412c9574-b4b5-435a-9478-888e62581a4a",
    "error": {
        "code": "0000",
        "description": "Success"
    }
}

Search

Key Request Parameters

Method: POST
URL: https://host-name/test/fleetmanagement/v1/tollobutransfer/search
Authentication Type: Basic authentication (Client ID and Client Secret)
apikey: Header (Client ID)

Sample Request

curl --location --request POST 'https://api-test.shell.com/test/fleetmanagement/v1/tollobutransfer/search' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic RVd5SXY4THBqeWdXM0xsS0REVW8wVlpNTjZKS3BxUmM6OU5XdlZMRVM3T3NHR1rpk==' \
--header 'apikey: EWyIv8LpjygW3LlKDDUo0VZMN6Jrpk' \
--data-raw '{
  "ObuId": "a544dbe6-3e81-4ece-bf42-96906dec3d6d",
  "VehicleId": "cf651180-fa00-462f-9c42-8d3177fbdbdf",
  "ColCoCode": 32,
  "PayerNumber": "CZ00001528",
  "AccountNumber": "CZ00001528"
}'

Sample Response

{
    "rowCount": 1,
    "currentPage": 1,
    "totalPages": 1,
    "entities": [
        {
            "obuId": "1cd567e3-e9e5-4e50-bbce-5dc1463d6935",
            "vehicleId": "931ceb46-589e-4d19-8b11-01ddca0ebc68",
            "customerId": "1b0ece8a-699f-49d3-a87f-cd746c0dadcf",
            "obuTransferRequestId": "928cda97-d277-ed11-ac20-14cb65651cac",
            "processStatus": 0
        }
    ],
    "requestId": "436538dd-e29c-460f-feab-2460445cd46d",
    "error": {
        "code": "0000",
        "description": "Success"
    }
}

Getting Started with On Board Unit (OBU) Management APIs

Authentication

Key Request Parameters

Exception Handling

Toll Order

Create

Key Request Parameters

Sample Request

Sample Response

Search

Key Request Parameters

Sample Request

Sample Response

Toll OBU Transfer Request

Create

Key Request Parameters

Sample Request

Sample Response

Search

Key Request Parameters

Sample Request

Sample Response

About us

Contact

Login to your account

Getting Started with On Board Unit (OBU) Management APIs

Authentication

Key Request Parameters

Exception Handling

Toll Order

Create

Key Request Parameters

Sample Request

Sample Response

Search

Key Request Parameters

Sample Request

Sample Response

Toll OBU Transfer Request

Create

Key Request Parameters

Sample Request

Sample Response

Search

Key Request Parameters

Sample Request

Sample Response

About us

Contact

Login to your account

Are you an external user?

Are you a Shell employee?