Quick Start Guide | Shell Developer Portal

Getting Started with Aviation Fuel (AVF) 2.0 Reseller APIs

The Aviation Reseller APIs is a web service that allows resellers to create, amend, cancel and status of the fuel request. Additionally, it enables to upload the Air Operator's Certificate (AOC) files. And also product search.

This API product includes multiple endpoints that developers use to create various user journey.

API Endpoint	API Functionality
/refdata/airportInfo	This endpoint fetches airport details. The airport is identified using a unique iataCode or icaoCode or countryName or airportName to retrieve apron and shipTo details.
/fuelRequest/create	This endpoint allows you to create the fuel requests.
/fuelRequest/uploadAOC/{fuelRequestId}	This endpoint allows you to upload an AOC file. The reseller has a five-minute window from the time of creation of fuel request to upload the file(s). The supported file formats are PDF, JPEG, and PNG. The maximum size for each file is 3 MB. You can upload up to four files with a unique names (duplicate file names are not allowed).
/fuelRequest/amend	This endpoint allows you to amend the fuel request.
/fuelRequest/status/{fuelRequestId}	This endpoint enables you to retrieve the status of a fuel request based on the fuelRequestId.
/fuelRequest/cancel	This endpoint allows you to cancel the fuel request.
/fuelRequest/products/search	This endpoint fetches the details of a product based on shipTo, soldTo and query parameter.

All the APIs are authenticated with standard OAuth2.0

Note: The section below lists sample API request and response with examples values for each parameter.

Authentication

Shell AVF APIs are secured by OAuth 2.0. It uses Client Credentials grant Type to allow the API consumer to access data. The end-to-end process is illustrated in the sequence diagram below:

sequenceDiagram Participant Partner Application Participant Authentication Server Participant APIMgnt Participant Shell Market Hub 2.0 Partner Application ->> Authentication Server: Initiate Authentication Flow activate Authentication Server note right of Partner Application: Input OAuth credentials (Partner application's specific (Client ID and Client Secret)) deactivate Authentication Server Authentication Server -->>+ Partner Application: Receives Bearer OR Access Token Partner Application ->> APIMgnt: Call the Functional Endpoint activate APIMgnt note right of Partner Application: Input Access Token, API Service Account Credentials (Client ID, Client Secret, apiKey) deactivate APIMgnt APIMgnt ->> Shell Market Hub 2.0: Initiate Authentication Flow activate Shell Market Hub 2.0 note right of APIMgnt: Input OAuth credentials (SMH Client ID, SMH Client Secret) deactivate Shell Market Hub 2.0 Shell Market Hub 2.0 -->> APIMgnt: Receives Access Token APIMgnt ->> Shell Market Hub 2.0: {Specific endpoint name of the API} Request + Access Token Shell Market Hub 2.0 -->> Partner Application: Successful Response for the specific endpoint API

Please note that there are two sets of credentials provided by Shell to access all the AVF functional API endpoints:

Initiate the OAuth 2.0 authentication flow with the Client Credentials (Client ID and Client Secret) provided by Shell to generate accessToken.
Use the Partner specific Client ID and Client secret provided by Shell along with the generated access token to access all the AVF functional API endpoints in the header to get the response.

Key Request Parameters

Once you receive the Client ID and Client Secret, next step is to call {Shell Environment}/as/token.oauth2 endpoint to authenticate. Following are the key parameters:

Method: POST
Authorization Type: OAuth 2.0
Auth URI: {Shell Environment}/as/token.oauth2
Client_Id: **** (OAuth Client ID)
Client Secret: **** (OAuth Client Secret)
Referrer-Policy: no-referrer
Grant Type: client_credentials

Sample cURL Request

curl --location --request POST '{Shell Environment}/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Referrer-Policy: no-referrer' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=***********' \
--data-urlencode 'grant_type=client_credentials'

On receiving the request, Shell Authorization system verifies all the parameters in the request and if everything checks out, it generates your access token and returns it in the response.

Sample Response

{
    "access_token": "***********",
    "token_type": "Bearer",
    "expires_in": 899,
}

The response contains the following parameters:

access_token: This is the token to be used to call the functional APIs
expires_in: The amount of seconds until the access token expires.
token_type: Bearer

Exception Handling

All error scenarios are returned with a response body and identifier.

{
      "error_description": "invalid client or client credentials",
      "error": "invalid_client"
}

HTTP Code	Description	Scenarios
400	Bad Request	If invalid scope passed to token URL. Invalid grant type passed to token URL
401	Unauthorized	You don't have valid authentication details for the requested resource

Airport Information

Introduction

This endpoint fetches airport details. The airport is identified using a unique iataCode or icaoCode or countryName or airportName to retrieve airport and shipTo details. The iataCode, icaoCode, and countryName works on exact search and airportName field works on approximate search.

Key Request Parameters

Method: GET
URI: {Shell Environment}/avf/v1/refdata/airportInfo
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key

Query Parameters: The query parameters allow to fetch the specific information about the airport.

Name	Description	Mandatory / Optional	Data Type	Example
iataCode	The abbreviation IATA stands for International Air Transport Association, which is a trade association that represents airlines worldwide. IATA defines the three-letter location codes used to identify destinations for fuel requests.	Optional	string	iataCode value is AAL : .../commerce/avf/v1/refdata/airportInfo ?iataCode=AAL
icaoCode	The abbreviation ICAO stands for International Civil Aviation Organization. The ICAO airport code is a four-character alphanumeric code that designates each airport. This code is used to identify the destinations for the fuel requests. This works on exact search.	Optional	string	icaoCode value is EKYT : .../commerce/avf/v1/refdata/airportInfo ?icaoCode=EKYT
airportName	The name of the airport.	Optional	string	Aalborg Airport, Frankfurt Airport, Indira Gandhi International Airport, etc. : .../commerce/avf/v1/refdata/airportInfo ?airportName=Aalborg
countryName	The name of the country. It will search all airports containing selected `countryName` in the country name field.	Optional	string	countryName is China : .../commerce/avf/v1/refdata/countryName ?countryName=China

Sample cURL Request

curl --location 'https://api-dev.shell.com/commerce/avf/v1/refdata/airportInfo' \
--header 'apiKey: 5Vl6wDGSQJX04AdKirIOLcAGpaZmivXG' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Imt0ZWEtckRDOFpNOVB5ZEVqQ2RnYXJ5bWFiWV9SUzI1NiIsInBpLmF0bSI6ImZ4eGcifQ.eyJzY29wZSI6IiIsImF1dGhvcml6YXRpb25fZGV0YWlsc' \
--header 'Cookie: PF=jFmX5d48wceDnRAIJmm9uL; ROUTE=.api-6f6b5c4dbd-nxmmf'

Sample Response

{
    "airports": [
        {
            "airportName": "Aalborg",
            "countryCode": "DK",
            "countryName": "Denmark",
            "iataCode": "AAL",
            "icaoCode": "EKYT",
            "isFuelingLocation": false
        }
    ],
    "currentQuery": {
        "query": {
            "value": "iataCode=AAL:relevance"
        },
        "url": "/search?q=iataCode%3DAAL%3Arelevance"
    },
    "pagination": {
        "currentPage": 0,
        "pageSize": 20,
        "sort": "relevance",
        "endCount": 1,
        "startCount": 1,
        "totalFavourites": 0,
        "totalFrequentlyOrdered": 0,
        "totalPages": 1,
        "totalResults": 1
    },
    "sorts": [
        {
            "code": "relevance",
            "selected": true
        },
        {
            "code": "iataCode-asc",
            "name": "Iata Code(ascending)",
            "selected": false
        },
        {
            "code": "iataCode-desc",
            "name": "Iata Code(descending)",
            "selected": false
        },
        {
            "code": "icaoCode-asc",
            "name": "Icao Code(ascending)",
            "selected": false
        },
        {
            "code": "icaoCode-desc",
            "name": "Icao Code(descending)",
            "selected": false
        },
        {
            "code": "airportName-asc",
            "name": "Airport Name(ascending)",
            "selected": false
        },
        {
            "code": "airportName-desc",
            "name": "Airport Name(descending)",
            "selected": false
        },
        {
            "code": "countryName-asc",
            "name": "Country Name(ascending)",
            "selected": false
        },
        {
            "code": "countryName-desc",
            "name": "Country Name(descending)"

         } 

    ] 

}

Create Fuel Request

Introduction

This endpoint allows you to create the fuel requests with fueling airport, destinations, and also supports AOC files.

For example: /fuelRequest/create?fields=FULL

Note: For Fields, possible values are BASIC and FULL. If you do not pass any value, then BASIC is considered.

Field	Description
BASIC	This parameter fetches the basic details for the fuelRequest.
FULL	This parameter fetches the full details of the payload values as in BASIC as well as the additional payload values which includes `bulkRequestId`, `endCustomerTobeFueled`, `isCaptainRequest`, `message`, `nextDestinations`, `endCustomerTobeFueled`, `product`, `product`, `updatedBy` and `updatedDate`.

Key Request Parameters

Method: POST
URI: {Shell Environment}/avf/v1/fuelRequest/create?fields={}
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key
  Note: This is a form-data.

Body :

createFuelRequestWsDTO: This is a mandatory field.

Name	Description	Mandatory / Optional	Data Type	Example
soldTo	This refers to a unique number provided during API implementation that can be passed during fuel requests.	Mandatory	string	0012657330
shipTo	This refers to a unique 'ship-to' number assigned to a delivery location or apron.	Mandatory	string	0010376390
userName	The email Id of the user who raises the fuel request.	Mandatory	string	avftestuser123@mailinator.com
unitCode	This is the unit of measure in which the product is sold. This is a case insensitive field. Accepted units are in L, Litre, UGL.	Mandatory	string	L, Litre, UGL
contractId	This is a unique contract Id of the customer.	Optional	string	0323259440
productId	This is a corresponding Id for each fuel request or product.	Mandatory	string	000000000400000391
captainRequest	The volume of fuel needed for an aircraft is determined based on the captainRequest. If the captainRequest is set to "true", volume is considered as input. If the captainRequest is set to "false" volumeRange is considered as in the input. If captainRequest is not passed (false) and both volume and volumeRange is passed, volumeRange is considered.	Optional	boolean	true, false
volume	The volume of fuel needed for an aircraft. The field “volume" is a double value that must take an absolute value. It is conditionally mandatory, which means that its requirement depends on the value of the "captainRequest" field.	Conditional Mandatory	string	20000
volumeRange	The volume range represents the minimum and maximum amount of fuel needed for an aircraft. This is a conditionally mandatory field from the input payload.	Conditional Mandatory	string	20000
additionalInfo	This additional message refers if the operator has any additional message to note. The character limit is 255 digits.	Optional	string	Other details (if applicable)
cardNetCardNumber	This is a unique number of the card.	Optional	string	7055925500134401354
aircraftTailNumber	This is the aircraft's unique tail number. It is alphanumeric and can contain only hyphens (-), spaces, and a maximum of 10 characters.	Mandatory	string	N892-SS
endCustomerName	The name of the customer. The length of the endCustomerName is up to 100 characters.	Mandatory	string	Emirates Airlines
flightNumber	The flight number.	Optional	string	UB1723
originCountryCode	This represents the ISO 3166-1 standard Alpha-2 code of the country.	Mandatory	string	HK
dateOfArrival	This is the arrival date and time of the flight or fuel request. dateOfArrival cannot be less than 7 days from todays date. The format is DDMMYYYY.	Mandatory	string	'08/02/2024 10:00'
dateOfDeparture	This is the departure date and time of the flight or fuel request. dateOfDeparture must be within 14 days of the dateOfArrival. The format is DDMMYYYY.	Mandatory	string	'08/02/2024 10:00'
airCraftType	This is aircraft type or type of flight. This is a case insensitive. The length allowed is up to 50 characters.	Optional	string	Cargo
fuelingAirport	This is the fueling airport.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
destinations	This is a list of destinations or locations which cannot be more than 4.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
finalDestination	This is the last destination.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
airportName	The name of the airport for the destination where fuel request is needed.	Mandatory	string	Indira Gandhi International Airport
iataCode	The abbreviation IATA stands for International Air Transport Association, which is a trade association that represents airlines worldwide. IATA defines the three-letter location codes used to identify destinations for fuel requests.	Mandatory	string	DEL
icaoCode	The abbreviation ICAO stands for International Civil Aviation Organization. The ICAO airport code is a four-character alphanumeric code that designates each airport. This code is used to identify the destinations for the fuel requests.	Mandatory	string	VIDP
countryName	The name of the country.	Mandatory	string	India
countryCode	This represents the ISO 3166-1 standard Alpha-2 code of the country.	Mandatory	string	IN

aocFiles: This key enables you to upload an AOC file. The supported file formats are PDF, JPEG, and PNG. The maximum size for each file is 3 MB. You can upload up to four files with a unique names (duplicate file names are not allowed). This is optional field.

Sample cURL Request for BASIC

curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/create?fields=BASIC' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--form 'createFuelRequestWsDTO="{
    \"soldTo\": \"0010219963\",
    \"shipTo\": \"0010376385\",
    \"userName\": \"avftestuser1223@mailinator.com\",
    \"contractId\": \"\",
    \"productId\": \"000000000400000391\",
    \"captainRequest\": false,
    \"volume\": \"20000\",
    \"volumeRange\": \"1100\",
    \"unitCode\": \"litre\",
    \"fuelingAirport\": {
        \"iataCode\": \"HKG\",
        \"icaoCode\": \"VHHH\",
        \"airportName\": \"Hong Kong\",
        \"countryCode\": \"HK\",
        \"countryName\": \"Hong Kong\"
    },
    \"additionalInfo\": \"jssjsadbad\",
    \"cardNetCardNumber\": \"7055938400125800207\",
    \"aircraftTailNumber\": \"ANY-KCH\",
    \"flightNumber\": \"1233\",
    \"endCustomerName\": \"san6s7SHOYSN&T+QJA6!tMfG7BbByXdjyWqg0uz&5dFkAKyS52@trXHGAT!9AkJJ9ANb5y87uE9X!+K1RSg2a!8wQ87G3T=jGZ2\",
    \"originCountryCode\": \"US\",
    \"dateOfArrival\": \"07/04/2024 10:00\",
    \"dateOfDeparture\": \"09/04/2024 10:00\",
    \"airCraftType\": \"cargo\",
    \"destinations\": [
        {
            \"iataCode\": \"DEL\",
            \"icaoCode\": \"VIDP\",
            \"airportName\": \"Delhi (Indira Gandhi Intl)\",
            \"countryCode\": \"IN\",
            \"countryName\": \"India\"
        }
    ],
    \"finalDestination\": {
        \"iataCode\": \"DEL\",
        \"icaoCode\": \"VIDP\",
        \"airportName\": \"Delhi (Indira Gandhi Intl)\",
        \"countryCode\": \"IN\",
        \"countryName\": \"India\"
    }
}";type=application/json' \
--form 'aocFiles=@"/C:/Users/Gayithri.M/OneDrive - Shell/Desktop/test_abc.pdf"'

Sample Response (with AOC file)

{ 

    "fuelRequestId": "00036001", 
     "message": "File Upload Successful",
     "status": "Pending",
     "userName": "avftestuser1223@mailinator.com"

Sample Response (without AOC file)

{
    "fuelRequestId": "00013007",
    "status": "Pending",
    "userName": "avftestuser1223@mailinator.com"
}

Sample cURL Request for FULL

curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/create?fields=FULL' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IlcwYTM2LXJYOS03bk1ET2Vxd2RjaW9KYlRJQV9SUzI1NiIsInBpLmF0bSI6ImZ4eGcifQ.eyJzY29wZSI6IiIsImF1dGhvcml6YXRpb25fZGV0YWlscyI6W10sImNsaWVudF9pZCI6ImU2OTE4ZjdhLWYwMDQtNDk4Yi1hY2ZiLTk1MDU4Yzc1MGM1MSIsImlzcyI6Imh' \
--header 'Cookie: PF=xHedbst93ijY9Uj7Md0cp2; ROUTE=.api-6d477fbcc7-24hm6' \
--form 'createFuelRequestWsDTO="{
  {
"soldTo": "0010219963",
"shipTo": "0012160579",
"userName": "avftestuser1223@mailinator.com",
"productId": "000000000400000049",
"captainRequest": false,
"volume": "20000",
"volumeRange": "1100",
"unitCode": "litre",
"fuelingAirport": {
"iataCode": "DXB",
"icaoCode": "OMDB",
"airportName": "Dubai Int. Airport",
"countryCode": "AE",
"countryName": "United Arab Emirates"
},
"additionalInfo": "jssjsadbad",
"aircraftTailNumber": "ANY-KCH",
"cardNetCardNumber":"7055938400125800363",
"contractId":"",
"flightNumber": "1233",
"endCustomerName": "emirates airlines",
"originCountryCode": "US",
"dateOfArrival": "05/05/2024 10:00",
"dateOfDeparture": "10/05/2024 10:00",
"airCraftType": "cargo",
"destinations": [
{
"iataCode": "DEL",
"icaoCode": "VIDP",
"airportName": "Delhi (Indira Gandhi Intl)",
"countryCode": "IN",
"countryName": "India"
}
],
"finalDestination": {
"iataCode": "DEL",
"icaoCode": "VIDP",
"airportName": "Delhi (Indira Gandhi Intl)",
"countryCode": "IN",
"countryName": "India"
}
}
    }
}";type=application/json' \
--form 'aocFiles=@"/C:/Users/Durga-Prasad.Nemali/Downloads/MicrosoftTeams-image (12).png"'

Sample Response for FULL


{
    "additinalInfo": "jssjsadbad",
    "apron": "HONG KONG INTERNATIONAL AIRPORT",
    "arrivalDate": "2024-05-05T10:00:00+0000",
    "bulkRequestId": "",
    "countryName": "Hong Kong",
    "departureDate": "2024-05-10T10:00:00+0000",
    "endCustomerTobeFueled": "emirates airlines",
    "flightNumber": "1233",
    "fuelRequestId": "00127000",
    "fuelingAirportName": "Hong Kong",
    "iataCode": "HKG",
    "icaoCode": "VHHH",
    "isCaptainRequest": false,
    "message": "File Upload Successful",
    "nextDestinations": [
        {
            "countryName": "India",
            "destinationAirportName": "Delhi (Indira Gandhi Intl)",
            "destinationId": "IN",
            "iataCode": "DEL",
            "icaoCode": "VIDP"
        },
        {
            "countryName": "India",
            "destinationAirportName": "Delhi (Indira Gandhi Intl)",
            "destinationId": "IN",
            "iataCode": "DEL",
            "icaoCode": "VIDP"
        }
    ],
    "origin": "United States",
    "product": "Jet A-1 / F-35 or AVTUR",
    "soldToName": "HORNBILL SKYWAYS SDN BHD M12",
    "soldToNumber": "0010219963",
    "status": "Pending",
    "tailNumber": "ANY-KCH",
    "unit": "LITRE",
    "updatedBy": "avftestuser1223@mailinator.com",
    "updatedDate": "2024-05-03T07:18:45+0000",
    "userName": "avftestuser1223@mailinator.com",
    "volume": "20000.0"
}

Upload AOC File

Introduction

This endpoint allows you to upload an Air Operator's Certificate (AOC) file. The reseller has a five-minute window from the time of creation of fuel request to upload the file(s). The supported file formats are PDF, JPEG, and PNG. The maximum size for each file is 3 MB. You can upload up to four files with a unique name (duplicate file names are not allowed).
Note: This is a form-data.

Key Request Parameters

Method: POST
URI: {Shell Environment}/avf/v1/fuelRequest/uploadAOC/{fuelRequestId}
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key
  Note: This is a form-data.

Body :

Name	Description	Mandatory / Optional	Data Type	Example
fuelRequestId	This is a unique fuel request ID.	Mandatory	string	00014000
aocFiles	This is an Air Operator's Certificate (AOC) file. The reseller has a five-minute window from the time of creation of fuel request to upload the AOC file(s). The supported file formats are PDF, JPEG, and PNG. The maximum size for each file is 3 MB. You can upload up to four files with a unique names (duplicate file names are not allowed). The supported file formats are PDF, JPEG, and PNG.	Mandatory	string	test.pdf

Sample cURL Request


curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/uploadAOC/00013011' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Imt0ZWEtckRDOFpNOVB5ZEVqQ2RnYXJ5bWFiWV9SUzI1NiIsInBpLmF0bSI6ImZ4eGcifQ.eyJzY29wZSI6IiIsImF1dGhvcml6YXRpb25fZGV0YW' \
--header 'Cookie: PF=bRYMa3218znbU4ztj2tXSj; ROUTE=.api-7df65ddf69-2bqgl' \
--form 'aocFiles=@"/test.aocfile - Shell/Desktop/test_abc.pdf"'

Sample Response

{
    "message": "File Upload Successful"
}

Fuel Request Status

Introduction

This endpoint enables you to retrieve the status of a fuel request based on the fuelRequestId.

Key Request Parameters

Method: GET
URI: {Shell Environment}/avf/v1/fuelRequest/status/{fuelRequestId}
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key

Body :

Name	Description	Mandatory / Optional	Data Type	Example
fuelRequestId	This is a unique fuel request ID. The status of the fuel requests can be viewed as Approved, Cancelled, Edited, Pending or Rejected.	Mandatory	string	00014000

Sample cURL Request


curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/status/00014000' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Indjb0RmQlM3LXRjYXAxbjdZMkFfeTZaNDVkQV9SUzI1NiIsInBpLmF0bSI6ImZ4eGcifQ.eyJzY29wZSI6IiIsImF1dGhvcml6YXRpb25fZGV0YWlscyI6W10sImNsaWVudF9pZCI6ImU2OTE4ZjdhLWYwMDQtNDk4Yi1hY2ZiLTk1MDU4Yzc1MGM1MSIsImlzcyI6Imh0dHBzOi8vc3NvLWRldi5zaGVsbC5jb20iLCJhdWQiOiIiLCJzdWIiOiJ0'

Sample Response

{
    "fuelRequestId": "00014000",
    "status": "Cancelled"
}

Amend Fuel Request

Introduction

This endpoint allows you to amend the created fuel request.

For example: /fuelRequest/amend/{fuelRequestId}?fields=FULL

Note: For Fields, possible values are BASIC and FULL. If you do not pass any value, then BASIC is considered.

Field	Description
BASIC	This parameter fetches the basic details for the amend fuelRequest.
FULL	This parameter fetches the full details of the payload values as in BASIC as well as the additional payload values which includes `bulkRequestId`, `endCustomerTobeFueled`, `isCaptainRequest,` `message`, `nextDestinations`, `endCustomerTobeFueled`, `product`, `product`, `updatedBy` and `updatedDate`.

Key Request Parameters

Method: POST
URI: {Shell Environment}/avf/v1/fuelRequest/amend/{fuelRequestId}
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: This is used to control the information sent from browsers to destination servers when clicking the hyperlinks.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key
  Note: This is a form-data.

Body :

amendFuelRequestWsDTO: This is mandatory field.

Name	Description	Mandatory / Optional	Data Type	Example
soldTo	This refers to a unique number provided during API implementation that can be passed during fuel requests.	Mandatory	string	0012657330
shipTo	This refers to a unique 'ship-to' number assigned to a delivery location or apron.	Mandatory	string	0010376390
userName	The email Id of the user who raises the fuel request.	Mandatory	string	avftestuser123@mailinator.com
unitCode	This is the unit of measure in which the product is sold. This is a case insensitive field. Accepted units are in L, Litre, UGL.	Mandatory	string	L, Litre, UGL
contractId	This is a unique contract Id of the customer.	Optional	string	0323259440
productId	This is a corresponding Id for each fuel request or product.	Mandatory	string	000000000400000391
captainRequest	The volume of fuel needed for an aircraft is determined based on the captainRequest. If the captainRequest is set to "true", volume is considered as input. If the captainRequest is set to "false" volumeRange is considered as in the input. If captainRequest is not passed (false) and both volume and volumeRange is passed, volumeRange is considered.	Optional	boolean	true, false
volume	The volume of fuel needed for an aircraft. The field “volume" is a double value that must take an absolute value. It is conditionally mandatory, which means that its requirement depends on the value of the "captainRequest" field.	Conditional Mandatory	string	20000
volumeRange	The volume range represents the minimum and maximum amount of fuel needed for an aircraft. This is a conditionally mandatory field from the input payload.	Conditional Mandatory	string	20000
additionalInfo	This additional message refers if the operator has any additional message to note. The character limit is 255 digits.	Optional	string	Other details (if applicable)
cardNetCardNumber	This is a unique number of the card.	Optional	string	7055925500134401354
aircraftTailNumber	This is the aircraft's unique tail number. It is alphanumeric and can contain only hyphens (-), spaces, and a maximum of 10 characters.	Mandatory	string	N892-SS
endCustomerName	The name of the customer. The length of the endCustomerName is up to 100 characters.	Mandatory	string	Emirates Airlines
flightNumber	The flight number.	Optional	string	UB1723
originCountryCode	This represents the code of the country.	Mandatory	string	HK
dateOfArrival	This is the arrival date and time of the flight or fuel request. dateOfArrival cannot be less than 7 days from todays date. The format is DDMMYYYY.	Mandatory	string	'08/02/2024 10:00'
dateOfDeparture	This is the departure date and time of the flight or fuel request. dateOfDeparture must be within 14 days of the dateOfArrival. The format is DDMMYYYY.	Mandatory	string	'08/02/2024 10:00'
airCraftType	This is aircraft type or type of flight. This is a case insensitive. The length allowed is up to 50 characters.	Optional	string	Cargo
fuelingAirport	This is the fueling airport.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
destinations	This is a list of destinations or locations which cannot be more than 4.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
finalDestination	This is the last destination.	Mandatory	object	Refer to airportName, iataCode, icaoCode, countryName and countryCode in the below rows of this table.
airportName	The name of the airport for the destination where fuel request is needed.	Mandatory	string	Indira Gandhi International Airport
iataCode	The abbreviation IATA stands for International Air Transport Association, which is a trade association that represents airlines worldwide. IATA defines the three-letter location codes used to identify destinations for fuel requests.	Mandatory	string	DEL
icaoCode	The abbreviation ICAO stands for International Civil Aviation Organization. The ICAO airport code is a four-character alphanumeric code that designates each airport. This code is used to identify the destinations for the fuel requests.	Mandatory	string	VIDP
countryName	The name of the country.	Mandatory	string	India
countryCode	This represents the ISO 3166-1 standard Alpha-2 code of the country.	Mandatory	string	IN

aocFiles: This key enables you to upload an AOC file. The supported file formats are PDF, JPEG, and PNG. The maximum size for each file is 3 MB. You can upload up to four files with a unique names (duplicate file names are not allowed). This is optional field.

If you select the aocFiles, you can view the sample response as "message": "File Upload Successful" as sample response along with fuelRequestId and userName details.

Sample cURL Request for FULL

curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/amend/00216000?fields=FULL' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--form 'amendFuelRequestWsDTO="{
\"soldTo\": \"0010219963\",
\"shipTo\": \"0012160579\",
\"userName\": \"avftestuser1223@mailinator.com\",
\"productId\": \"000000000400000049\",
\"captainRequest\": false,
\"volume\": \"20000\",
\"volumeRange\": \"1100\",
\"unitCode\": \"litre\",
\"fuelingAirport\": {
\"iataCode\": \"DXB\",
\"icaoCode\": \"OMDB\",
\"airportName\": \"Dubai Int. Airport\",
\"countryCode\": \"AE\",
\"countryName\": \"United Arab Emirates\"
},
\"additionalInfo\": \"jssjsadbad\",
\"aircraftTailNumber\": \"ANY-KCH\",
\"cardNetCardNumber\":\"7055938400125800363\",
\"contractId\":\"\",
\"flightNumber\": \"1233\",
\"endCustomerName\": \"emirates airlines\",
\"originCountryCode\": \"US\",
\"dateOfArrival\": \"08/05/2024 10:00\",
\"dateOfDeparture\": \"10/05/2024 10:00\",
\"airCraftType\": \"cargo\",
\"destinations\": [
{
\"iataCode\": \"DEL\",
\"icaoCode\": \"VIDP\",
\"airportName\": \"Delhi (Indira Gandhi Intl)\",
\"countryCode\": \"IN\",
\"countryName\": \"India\"
}
],
\"finalDestination\": {
\"iataCode\": \"DEL\",
\"icaoCode\": \"VIDP\",
\"airportName\": \"Delhi (Indira Gandhi Intl)\",
\"countryCode\": \"IN\",
\"countryName\": \"India\"
}
}";type=application/json' \
--form 'aocFiles=@"/C:/Users/Gayithri.M/OneDrive - Shell/Desktop/test_abc.pdf"'

Sample Response for FULL

{
    "additinalInfo": "jssjsadbad",
    "apron": "DUBAI GA APRON",
    "arrivalDate": "2024-05-08T10:00:00+0000",
    "bulkRequestId": "",
    "countryName": "United Arab Emirates",
    "departureDate": "2024-05-10T10:00:00+0000",
    "endCustomerTobeFueled": "emirates airlines",
    "flightNumber": "1233",
    "fuelRequestId": "00216000",
    "fuelingAirportName": "Dubai Int. Airport",
    "iataCode": "DXB",
    "icaoCode": "OMDB",
    "isCaptainRequest": false,
    "message": "File Upload Successful",
    "nextDestinations": [
        {
            "countryName": "India",
            "destinationAirportName": "Delhi (Indira Gandhi Intl)",
            "destinationId": "IN",
            "iataCode": "DEL",
            "icaoCode": "VIDP"
        },
        {
            "countryName": "India",
            "destinationAirportName": "Delhi (Indira Gandhi Intl)",
            "destinationId": "IN",
            "iataCode": "DEL",
            "icaoCode": "VIDP"
        }
    ],
    "origin": "United States",
    "product": "Jet A-1 / F-35 or AVTUR",
    "soldToName": "HORNBILL SKYWAYS SDN BHD M12",
    "soldToNumber": "0010219963",
    "status": "Edited",
    "tailNumber": "ANY-KCH",
    "unit": "LITRE",
    "updatedBy": "avftestuser1223@mailinator.com",
    "updatedDate": "2024-05-14T08:54:07+0000",
    "userName": "avftestuser1223@mailinator.com",
    "volume": "0.0",
    "volumeRange": "1100"
}

Cancel Fuel Request

Introduction

This endpoint allows you to cancel a fuel request.

Key Request Parameters

Method: POST
URI: {Shell Environment}/avf/v1/fuelRequest/cancel/
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key
  Note: This is a raw data.

Body:

Name	Description	Mandatory / Optional	Data Type	Example
fuelRequestId	This is a unique fuel request ID.	Mandatory	string	00014000
userName	The email Id of the user.	Mandatory	string	avftestuser123@mailinator.com
reasonForUpdate	The description of reason to cancel the fuel request. The length allowed is 4000 characters.	Optional	string	Change in the requirement.

Sample cURL Request

curl --location 'https://api-dev.shell.com/commerce/avf/v1/fuelRequest/cancel' \
--header 'apiKey: 6M4LdZEDloUYhAPY62qzVe5vyqk4iVka' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Imt0ZWEtckRDOFpNOVB5ZEVqQ2RnYXJ5bWFiWV9SUzI1NiIsInBpLmF0bSI6ImZ4eGcifQ.eyJzY29wZSI6IiIsImF1dGhvcml6YXRpb25fZGV0YWlscyI6W10sImNsaWVudF9pZCI6ImU2OTE4ZjdhLWYwMDQtNDk4Yi1hY2ZiLTk1MDU4Yzc1' \
--header 'Cookie: PF=jFmX5d48wceDnRAIJmm9uL; ROUTE=.api-6f6b5c4dbd-nxmmf' \
--data-raw '{
  "fuelRequestId":"00014000",
  "userName":"avftestuser1223@mailinator.com",
  "reasonForUpdate": "test check"
}'

Sample Response


{
    "fuelRequestId": "00014000",
    "status": "Cancelled",
    "userName": "avftestuser1223@mailinator.com"
}

Search Products

Introduction

This endpoint enables you to retrieve the products based on the shipTo, soldTo and query parameter.

Key Request Parameters

Method: GET
URI: {Shell Environment}/avf/v1/products/search/
Headers:
- client_id: API Client ID
- client_secret: API Client Secret
- Authorization: Bearer access_token (Access Token generated from the OAuth end point)
- RequestId: The RequestId must be a unique identifier value that can be used by the consumer to correlate each request/response.
- Referrer-Policy: no-referrer
- apiKey: This is a unique Shell API key

Query Parameters: The query parameters allow to fetch the specific information about the products.

Example: query=Jet, query=Jet A

Name	Description	Mandatory / Optional	Data Type	Example
shipTo	This refers to a unique 'ship-to' number assigned to a delivery location or apron.	Mandatory	string	0010376390
soldTo	This refers to a unique number provided during API implementation that can be passed during fuel requests.	Mandatory	string	0012657330

Sample cURL Request


curl --location 'https://api-dev.shell.com/commerce/avf/v1/products/search?shipTo=0011936715&soldTo=0010219963&query=Jet' \
--header 'apiKey: 5Vl6wDGSQJX04AdKirIOLcAGpaZmivXG' \
--header 'RequestId: 9d2dee33-7803-485a-a2b1-2c7538e597ee' \
--header 'client_secret: 1wqPjAu7E+TlunglLD8sF3Lm5BG6vCxbVqEntR4g6jo=' \
--header 'client_id: e6918f7a-f004-498b-acfb-95058c750c51' \
--header 'Referrer-Policy: no-referrer'

Sample Response


{
    "type": "productCategorySearchPageWsDTO",
    "currentQuery": {
        "query": {
            "value": "Jet:name-asc"
        },
        "url": "/search?q=Jet%3Aname-asc"
    },
    "freeTextSearch": "Jet",
    "pagination": {
        "currentPage": 0,
        "pageSize": 20,
        "sort": "name-asc",
        "endCount": 0,
        "startCount": 0,
        "totalFavourites": 0,
        "totalFrequentlyOrdered": 0,
        "totalPages": 1,
        "totalResults": 1
    },
    "products": [
        {
            "baseProduct": "002C0948",
            "baseUom": "KG",
            "brand": "Jet A",
            "code": "000000000400004031",
            "displayCode": "400004031",
            "images": [
                {
                    "baseUrl": "https://api.s1.markethub2.shell.com",
                    "format": "68Wx68H",
                    "imageType": "PRIMARY",
                    "url": "/medias/default-smh-bulk-image-68Wx68H?context=bWFzdGVyfGltYWdlc3wxMDE2fGltYWdlL2pwZWd8YURFeUwyZzNNQzg0T0RRMU5Ea3dOekUyTnpBeUwyUmxabUYxYkhSZmMyMW9YMkoxYkd0ZmFXMWhaMlZmTmpoWGVEWTRTQXwyMDNjM2VlOGM0NWU1MzM3ZDczZmIwZDIxZTI5ODU3ODk3Y2EzMDVjNWMyOTk3ODhhNTM2NWE1ODEwMjM0NmE1"
                },

                {
                    "baseUrl": "https://api.s1.markethub2.shell.com",
                    "format": "54.4Wx54.4H",
                    "imageType": "PRIMARY",
                    "url": "/medias/default-smh-bulk-image-54.4Wx54.4H?context=bWFzdGVyfGltYWdlc3w3MjR8aW1hZ2UvanBlZ3xhR1F4TDJnM015ODRPRFExTkRrd09EUTNOemMwTDJSbFptRjFiSFJmYzIxb1gySjFiR3RmYVcxaFoyVmZOVFF1TkZkNE5UUXVORWd8N2Q4YTMyNTA5M2I4MzhjYmFlYmU4ZWQ2N2FmYTlkZmRkMTNlMzkyM2ZlZGUxNDA5NzI5NWUwMzRjM2VlOTJiNA"
                }
            ],
            "materialType": "bulk",
            "name": "Jet A",
            "packDesc": "BULK",
            "salestext": "<em class=\"search-results-highlight\">Jet</em> A BULK",
            "subGroupDesc": "Jet A",
            "unit": "UG6",
            "url": "/Root-Category/Fuels/Jet-A/p/000000000400004031",
            "volumePricesFlag": false
        }
    ],
    "sorts": [
        {
            "code": "name-asc",
            "name": "Name (Ascending)",
            "selected": true
        },
        {
            "code": "name-desc",
            "name": "Name (Descending)",
            "selected": false
        },

        {
            "code": "relevance",
            "name": "Relevance",
            "selected": false
        }
    ]
}

Getting Started with Aviation Fuel (AVF) 2.0 Reseller APIs

Authentication

Key Request Parameters

Sample cURL Request

Sample Response

Exception Handling

Airport Information

Introduction

Key Request Parameters

Sample cURL Request

Sample Response

Create Fuel Request

Introduction

Key Request Parameters

Sample cURL Request for BASIC

Sample Response (with AOC file)

Sample Response (without AOC file)

Sample cURL Request for FULL

Sample Response for FULL

Upload AOC File

Introduction

Key Request Parameters

Sample cURL Request

Sample Response

Fuel Request Status

Introduction

Key Request Parameters

Sample cURL Request

Sample Response

Amend Fuel Request

Introduction

Key Request Parameters

Sample cURL Request for FULL

Sample Response for FULL

Cancel Fuel Request

Introduction

Key Request Parameters

Sample cURL Request

Sample Response

Search Products

Introduction

Key Request Parameters

Sample cURL Request

Sample Response

About us

Contact

Login to your account

Are you an external user?

Are you a Shell employee?