api integration documentation - datacom · 2019-05-31 · p a g e 4 | 38 1. search flights...

SOFTWARE DEPARTMENT DATACOM | VIETNAM

API INTEGRATION DOCUMENTATION AIR TICKET & DATA

P a g e 1 | 38

INDEX CONTENT PAGE

Overview 2

System functions 3

1. Search flight 4

1.1. Default flight search 5

1.2. Lowest fare search ( flexible +7 days) 12

1.3. Lowest fare search in a specific month 15

2. Retrieve Baggage 18

3. Retrieve Fare rules 22

4. Check Availability 22

5. Booking 25

5.1. Standard booking 26

5.2. Indirect booking 30

5.3. Direct booking 33

6. Issue ticket 35

7. Booking management 36

7.1. Void ticket 37

P a g e 2 | 38

Overview ▪ Responsed Data is in JSON format

▪ API URL Desciption:

http://platform.datacom.vn/swagger/ui/index#/Flights

▪ Passenger type code:

- Adult – Code: ADT

- Child – Code: CHD

- Infant – Code: INF

▪ Airlines code (2 characters) , for example : VN, VJ, BL, JQ, QR, SA....

▪ City/Airport code (3 characters), for example: HAN, SGN, DAD, HPH…

▪ API Authentication:

API Authentication

Field Name Required Description Data Type Example

HeaderUser Yes API authen account string

HeaderPass Yes API authen password string

ProductKey No Customer’s Product key string

Language No Language: vi or en string

AgentAccount Yes Agent account string

AgentPassword Yes Agent Password : “admin”

string

Authentication account is mandatory for all API method, and applied for all below

index/contents/headings.

http://platform.datacom.vn/swagger/ui/index#/Flights

P a g e 3 | 38

System functions

Search & Book Overview model

Booking Management

Step 1

• flights search

Step 2

• Baggage retrieval

Step 3

• Fare Rules retrieval

Step 4

• Booking

Step 5

• Issue ticket

Exchange Ticket

Applied by specific Airlines' Rules and Conditions

Purchase extra baggages


VOID Ticket


P a g e 4 | 38

1. Search flights

Introduction ▪ This function allows Partner to search flights and fares on domestic and international

carriers. Data structures are designed by unique mode that is convenient for software

development.

▪ System allows to search:

- Domestic flights in Viet Nam.

- International flights.

- Flights on LCC (Low Cost Carriers) : VJ, JQ, QH, VN.

- Flights on Traditional Airlines

▪ Datacom supplies 3 types of search:

- Standard search: response flight and fare options from platting carriers. Partners are

able to search by:

✓ One way flights

✓ Return flights

✓ Multiple city

- Lowest fare on a specific date (flexible +/- 7 days): response flights with the lowest

fare on a specific date. This method allows partners to build searching function

flexibly ( + - 7 days). Data are from the cache database of Datacom.

- Lowest fare in a specific month: response flights with the lowest fare for all days in

a specific month. This method allows partners to build searching function of the low

fares in a specific month. Data are from the cache database of Datacom.

▪ Datacom will advise partners to choose the most accordant resource as partner’s

requests/demands: Service package, connecting registration with airlines and GDS.

P a g e 5 | 38

1.1. Default flights search

Description ▪ This method allows to search flights:

- One way.

- Return.

- Multiple city.

▪ Advanced searching options:

- Searching for specific airlines.

- Optional fare combined mode.

▪ Example for flights search:

Domestic

International

P a g e 6 | 38

Request ▪ URL: http://platform.datacom.vn/flights/search

▪ Method: POST

▪ Structure of request data:

{

"Adt": 0,

"Chd": 0,

"Inf": 0,

"ViewMode": "string",

"ListFlight": [{

"StartPoint": "string",

"EndPoint": "string",

"DepartDate": "string",

"Airline": "string"

}

],

"HeaderUser": "string",

"HeaderPass": "string",

"ProductKey": "string",

"Language": "string",

"AgentAccount": "string",

"AgentPassword": "string"

}

Description of SearchRequest


Adt Yes Number of Adults int 1

Chd Yes Number of children int 0

Inf Yes Number of Infants int 0

ViewMode No Mode to view fares (Default mode leaves Blank)

string

ListFlight Yes List of requested flights FlightRequest[]

API Authentication

Yes Refer to: API Authentication

Description of FlightRequest


StartPoint Yes Departure City/Airport code

string HAN

EndPoint Yes Arrival City/Airport Code string SGN

DepartDate Yes Departure date (format ddMMyyyy)

string 17092019

Airline No Airline code or Blank for neutral searching

string VN

▪ Guide and Notes:

- The number of passengers is max of 9.

- The number of Infants must be less than or equal to the number of accompanied

Adults.

- ViewMode:

✓ ViewMode = default or blank: default mode

✓ ViewMode = combine: the pairs of flights on LCCs will be combined

automatically into FareData, and the structure of international flights on

GDS will be remained on the system.

http://platform.datacom.vn/flights/search

P a g e 7 | 38

✓ ViewMode = split: System will split automatically the flights in FareData

into FareData of similar prices with single pair of flights . The flights on

domestic airlines are unchanged.

- One way flight: ListFlight contains 1 element FlightRequest

- Return flight: ListFlight contains 2 elements FlightRequest, valid for:

✓ FlightRequest[0].StartPoint = FlightRequest[1].EndPoint ✓ FlightRequest[0].EndPoint = FlightRequest[1].StartPoint ✓ FlightRequest[0].DepartDate <= FlightRequest[1]. DepartDate

- Multiple city: ListFlight contains >= 2 elements FlightRequest . If ListFlight contains

2 elements, but StartPoint is different from EndPoint (no valid for the above

response of return flight), system responses multiple city.

- To search flights for specific airlines, partners need to input the code of airlines in to

the Airline field. System will search and return data of the assigned airlines.

▪ Example:

One way {

"Adt": 1,

"Chd": 1,

"Inf": 1,

"ViewMode": "",

"ListFlight": [{

"StartPoint": "HAN",

"EndPoint": "SGN",

"DepartDate": "17092019",

"Airline": ""

}

],

"HeaderUser": "datacom",

"HeaderPass": "xxxxxxx",

"ProductKey": "xxxxxxxxxxxx",

"Language": "vi",

"AgentAccount": "DC00001",

"AgentPassword": "xxxxxx"

}

Return {

"Adt": 1,

"Chd": 1,

"Inf": 1,

"ViewMode": "",

"ListFlight": [{


"EndPoint": "SGN",


"Airline": ""

},{

"StartPoint": "SGN",

"EndPoint": "HAN",


"Airline": ""

}

],




"Language": "vi",



}

P a g e 8 | 38

Multiple city {

"Adt": 1,

"Chd": 1,

"Inf": 1,

"ViewMode": "",

"ListFlight": [{


"EndPoint": "DAD",


"Airline": ""

},{

"StartPoint": "DAD",

"EndPoint": "SGN",


"Airline": ""

},{

"StartPoint": "SGN",

"EndPoint": "HAN",


"Airline": ""

}

],




"Language": "vi",



}

Response ▪ Structure of response data: SearchResponse

{

"FlightType": "string",

"Session": "string",

"Itinerary": 0,

"ListFareData": [

{

"FareDataId": 0,

"Airline": "string",

"Itinerary": 0,

"Leg": 0,

"Promo": true,

"Currency": "string",

"System": "string",

"Adt": 0,

"Chd": 0,

"Inf": 0,

"FareAdt": 0,

"FareChd": 0,

"FareInf": 0,

"TaxAdt": 0,

"TaxChd": 0,

"TaxInf": 0,

"FeeAdt": 0,

"FeeChd": 0,

"FeeInf": 0,

"ServiceFeeAdt": 0,

"ServiceFeeChd": 0,

"ServiceFeeInf": 0,

"TotalNetPrice": 0,

"TotalServiceFee": 0,

"TotalPrice": 0,

"ListFlight": [

P a g e 9 | 38

{

"FlightId": 0,

"Leg": 0,




"StartDate": "2019-04-09T19:49:45.889Z",

"EndDate": "2019-04-09T19:49:45.889Z",

"FlightNumber": "string",

"StopNum": 0,

"HasDownStop": true,

"Duration": 0,

"NoRefund": true,

"GroupClass": "string",

"FareClass": "string",

"Promo": true,

"FlightValue": "string",

"ListSegment": [

{

"Id": 0,




"StartTime": "2019-04-09T19:49:45.889Z",

"EndTime": "2019-04-09T19:49:45.890Z",


"Duration": 0,

"Class": "string",

"Plane": "string",

"StartTerminal": "string",

"EndTerminal": "string",

"HasStop": true,

"StopPoint": "string",

"StopTime": 0,

"DayChange": true,

"StopOvernight": true,

"ChangeStation": true,

"ChangeAirport": true,

"LastItem": true,

"HandBaggage": "string"

}

]

}

]

}

],

"Status": true,

"ErrorCode": "string",

"Message": "string"

}

Description of SearchResponse

Field Name Description Data Type Example

Status Connection result bool True

ErrorCode Error code (if available) string

Message Error message (if available) string

FlightType Flight type domestic international

string Domestic

Session Session string DC000HANSG…

Itinerary Itinerary type int 1

ListFareData List of data and fares FareData[]

Description of FareData


FareDataId FareData Identification int 1

P a g e 10 | 38

Airline Airlines string VN

Itinerary Itinerary type int 1

Leg Segment order int 0

Promo Promotion fare. If Promo = True: Unable to hold this fare option

bool False

Currency Currency code string VND

System Data system string LCC

Adt Number of Adults int 1

Chd Number of children int 0

Inf Number of Infants int 0

FareAdt Adult fare double 1.000.000

FareChd Child fare double 750.000

FareInf Infant fare double 100.000

TaxAdt Tax for Adult double 150.000

TaxChd Tax for child double 75.000

TaxInf Tax for infant double 10.000

FeeAdt Fee for Adult double 80.000

FeeChd Fee for Child double 50.000

FeeInf Fee for Infant double 30.000

ServiceFeeAdt Service fee for Adult double 100.000

ServiceFeeChd Service fee for Child double 100.000

ServiceFeeInf Service fee for Infant double 100.000

TotalNetPrice Total price excluding service fee (Airline’s net fare)

double 1.850.000

TotalServiceFee Total service fee double 300.000

TotalPrice Total Price double 2.150.000

ListFlight List of flight options Flight[]

Description of Flight


FlightId Flight ID int 1

Airline Airlines string VN

Leg Sector/segment order int 0

StartPoint Departure city/airport code string HAN

EndPoint Arrival City/airport code string SGN

StartDate Departure Date DateTime

EndDate Arrival Date DateTime

FlightNumber Flight number (First) string VN123

StopNum Number of stop point int 0

HasDownStop Number of Transit point bool False

Duration Tota Flying time int 120

NoRefund Non refundable flight bool False

GroupClass Class type string Economy

FareClass Fare Class string M

Promo Promotion fare. If Promo = True: Unable to hold this flight

bool False

FlightValue Flight Value string

ListSegment List of flight segment Segment[]

Description of Segment


Id Segment ID int 1

Airline Airline string VN

StartPoint Departure Airport code string HAN

EndPoint Arrival Airport code string SGN

P a g e 11 | 38

StartTime Departure time DateTime

EndTime Arrival time DateTime

FlightNumber Flight number (first) string VN123

Duration Flying time int 120

Class Class code string M

Plane Plane type string 330

StartTerminal Departure Terminal string T1

EndTerminal Arrival Terminal string T2

HasStop Has stop point? bool False

StopPoint Stop point code string

StopTime Stopping time int 0

DayChange Change into next day? bool False

StopOvernight Overnight stop? bool False

ChangeStation Change station? bool False

ChangeAirport Change Airport? bool False

LastItem Last flight in the list bool True

HandBaggage Hand baggage allowance string 7kg

▪ Notes:

- If Promo = True: This flight or fare option can not hold.

- If total hours between StartDate and now less than 24hrs, this flight can not hold.

P a g e 12 | 38

1.2. Lowest fare for specific date

Description ▪ This function allows to search the lowest fare for specific Itinerary on specific date.

▪ This function allows to develop function to display the lowest fare on nearby days:

Request ▪ URL: http://platform.datacom.vn/flights/searchmin

▪ Method: POST


{

"FlightRequest": {




"Airline": "string"

},







}

Description of SearchMinRequest


FlightRequest Yes FlightRequest

API Authentication Yes Refer to: API Authentication

Please refer to Description of FlightRequest in the page 4

Response ▪ Structure of response data:

{

"MinFlight": {

"FareDataId": 0,


"Itinerary": 0,

"Leg": 0,

"Promo": true,


"System": "string",

"Adt": 0,

"Chd": 0,

"Inf": 0,

"FareAdt": 0,

"FareChd": 0,

"FareInf": 0,

"TaxAdt": 0,

"TaxChd": 0,

"TaxInf": 0,

"FeeAdt": 0,

http://platform.datacom.vn/flights/searchmin

P a g e 13 | 38

"FeeChd": 0,

"FeeInf": 0,

"ServiceFeeAdt": 0,

"ServiceFeeChd": 0,

"ServiceFeeInf": 0,

"TotalNetPrice": 0,


"TotalPrice": 0,

"ListFlight": [

{

"FlightId": 0,

"Leg": 0,




"StartDate": "2019-04-09T17:24:52.957Z",

"EndDate": "2019-04-09T17:24:52.957Z",


"StopNum": 0,


"Duration": 0,

"NoRefund": true,



"Promo": true,


"ListSegment": [

{

"Id": 0,




"StartTime": "2019-04-09T17:24:52.957Z",

"EndTime": "2019-04-09T17:24:52.957Z",


"Duration": 0,

"Class": "string",

"Plane": "string",



"HasStop": true,


"StopTime": 0,

"DayChange": true,




"LastItem": true

}

]

}

]

},

"Status": true,


"Message": "string"

}

Description of SearchMinResponse



ErrorCode Error Code (if available) string

Message Error Message (if available) string

MinFlight Lowest fare FareData

Please refer to Description of FareData in the page 6

P a g e 14 | 38

1.3. Lowest fare in a specific month

Description ▪ This function allows to search the lowest fare of specific itinerary on specific airlines on all

days in a month.

▪ This function allows to develop searching function of low fare in a month:

▪ API returns list of lowest fares on specific LCCs on a day in a month.

▪ Notes: This function is currently available only for domestic flights and on LCCs.

Request ▪ URL: http://platform.datacom.vn/flights/searchmonth

▪ Method: POST

▪ Structure of sending data:

{




"Month": 0,

"Year": 0,







}

Description of SearchMonthRequest


StartPoint Yes Departure City/Airport code string HAN

EndPoint Yes Arrival City/Airport code string SGN

http://platform.datacom.vn/flights/searchmonth

P a g e 15 | 38

Airline No Airline code. Leaving value ALL or Blank for searching flights for all LCCs

string ALL

Month Yes Month int 6

Year Yes Year int 2019


Response ▪ Structure of returned data:

{

"ListMinPrice": [

{

"DepartDate": "2019-04-09T17:56:53.718Z",

"ListFareData": [

{

"FareDataId": 0,


"Itinerary": 0,

"Leg": 0,

"Promo": true,


"System": "string",

"Adt": 0,

"Chd": 0,

"Inf": 0,

"FareAdt": 0,

"FareChd": 0,

"FareInf": 0,

"TaxAdt": 0,

"TaxChd": 0,

"TaxInf": 0,

"FeeAdt": 0,

"FeeChd": 0,

"FeeInf": 0,

"ServiceFeeAdt": 0,

"ServiceFeeChd": 0,

"ServiceFeeInf": 0,

"TotalNetPrice": 0,


"TotalPrice": 0,

"ListFlight": [

{

"FlightId": 0,

"Leg": 0,




"StartDate": "2019-04-09T17:56:53.718Z",

"EndDate": "2019-04-09T17:56:53.718Z",


"StopNum": 0,


"Duration": 0,

"NoRefund": true,



"Promo": true,


"ListSegment": [

{

"Id": 0,


P a g e 16 | 38



"StartTime": "2019-04-09T17:56:53.718Z",

"EndTime": "2019-04-09T17:56:53.718Z",


"Duration": 0,

"Class": "string",

"Plane": "string",



"HasStop": true,


"StopTime": 0,

"DayChange": true,




"LastItem": true

}

]

}

]

}

]

}

],

"Status": true,


"Message": "string"

}

Description of SearchMonthResponse



ErrorCode Error Code (If available) string

Message Error Message (If available) string

ListMinPrice List of lowest fare MinPrice[]

Description of MinPrice


DepartDate Date in Month bool 2019-06-01

ListFareData List of fares and data FareData[]

Please refer to Description of FareData in Heading 1.1

P a g e 17 | 38

2. Retrieve baggage Description

▪ This function allows to extract extra-baggage information on each flight.

▪ Airlines allow passengers to purchase additional baggage:

- Vietjet Air (VJ).

- Jetstar Pacific (JQ).

- Bamboo Airways (QH), with BAMBOOECO.

▪ Add-on baggage is charged per passenger, on each segment/sector. To purchase allowance

baggage, it is requested to import information of baggage package in passenger list (further

Description in index: Book).

▪ Once Partner requests API flight information (from result of SearchResponse) to extract,

system will search and return add-on baggage packages if they are available.

Request ▪ URL: http://platform.datacom.vn/flights/getbaggage

▪ Method: POST


{

"ListFareData": [

{


"FareDataId": 0,

"ListFlight": [

{

"FlightValue": "string"

}

]

}

],







}

Description of BaggageRequest


ListFareData Yes List of flight requested with related baggage data

FareDataInfo[]


Description of FareDataInfo


Session Yes Working session string DC0001HAN…

FareDataId Yes Fare Data ID int 15

ListFlight Yes List of requested flight FlightInfo[]

Description of FlightInfo


FlightValue Yes Value of flight string 1VJ123HAN…

http://platform.datacom.vn/flights/getbaggage

P a g e 18 | 38

▪ Implementation method:

- When passengers select a flight from search result , the partner uses the filght

information to build BaggageRequest and send to API to request baggage

allowance.

o Get information Session of searching result of SearchResponse from API

response.

o Get information FareDataId from FareData that purchaser selected .

o Get list of FlightValue that purchaser selected in data Flight

▪ Example:

{

"ListFareData": [

{

"Session": "DM0VJHANSGN090419VJHANSGN090419111092216",

"FareDataId": 7,

P a g e 19 | 38

"ListFlight": [{

"FlightValue": "0VJ197K_EcoHANSGN201904092145"

},{

"FlightValue": "0VJ185H_EcoHANSGN201904092115"

}

]

}

],







}

Response ▪ Structure of response data: BaggageResponse

{

"ListBaggage": [

{


"Leg": 0,

"Route": "string",

"Code": "string",


"Name": "string",

"Price": 0,

"Value": "string"

}

],

"Status": true,


"Message": "string"

}

Description of BaggageResponse





ListBaggage List of baggage Baggage[]

Description of Baggage


Airline Airline code string VJ

Leg Sector order int 0

Route Value of sector/segment string HANSGN

Code Cod of Baggage package string 15

Currency Currency code string VND

Name Name of baggage package string 15kg baggage

Price Price of baggage package double 154.000

Value Weight of baggage string 15kg

P a g e 20 | 38

3. Retrieve fare rules Description

▪ This function allows to extract fare rules of each airlines on each specific sector.

▪ Responsed Fare rules of international flights on GDS are original fare rules of carriers in

English.

▪ Fare rules on LCCs are imported from partner’s manual database in API administration.

Request ▪ URL: http://platform.datacom.vn/flights/getfarerules

▪ Method: POST


{

"ListFareData": [

{


"FareDataId": 0,

"ListFlight": [

{


}

]

}

],







}

Description of FareRuleRequest


ListFareData Yes List of FareData to extract baggage field

FareDataInfo[]

API Authentication Yes Refer to API Authentication

Refer to the Description of FareDataInfo in Heading 2. Retrieve allowance baggage

▪ Tips: Building structure of FareRuleRequest is same to the above retrieval of allowance

baggage by change of URL request.


{

"ListFareRules": [

{

"Route": "string",

"FareBasis": "string",

"ListRulesGroup": [

{

"RulesTitle": "string",

"ListRulesText": [

"string"

]

}

]

}

http://platform.datacom.vn/flights/getfarerules

P a g e 21 | 38

],

"Status": true,


"Message": "string"

}

Description of FareRuleResponse





ListFareRules List of baggage package FareRules[]

Description of FareRules


Route Information of sector string HANSGN

FareBasis Information of fare basic string PXNAET

ListRulesGroup List of rules group RulesGroup[]

Description of RulesGroup


RulesTitle Title of rules string PENALTY

ListRulesText List of rules’ text string[] ….

P a g e 22 | 38

4. Check Availability Description

▪ This function allows to check availability and fare of the flight before holding booking.

▪ Hold booking is successful only once the flight is available. In case of changed fare, the flight

will be remarked to hold booking with the lastest fare.

Request ▪ URL: http://platform.datacom.vn/flights/verifyflight

▪ Method: POST


{

"ListFareData": [

{


"FareDataId": 0,

"AutoIssue": false,

"ListFlight": [

{


}

]

}

],







}

Description of FareRuleRequest


ListFareData Yes List of FareData is required to search baggage information

FareDataInfo[]


Refer to the Description of FareDataInfo in Heading 2. Retrieve allowance baggage

▪ Tips: Coding structure VerifyRequest is same way to retrieve the above baggage . Only

Have URL request changed.


{

"ListFareStatus": [

{

"Status": true,

"Remark": "string",

"Price": 0,

"Difference": 0,


"FareData": {

"FareDataId": 0,


"Itinerary": 0,

http://platform.datacom.vn/flights/verifyflight

P a g e 23 | 38

"Leg": 0,

"Promo": true,


"System": "string",

"Adt": 0,

"Chd": 0,

"Inf": 0,

"FareAdt": 0,

"FareChd": 0,

"FareInf": 0,

"TaxAdt": 0,

"TaxChd": 0,

"TaxInf": 0,

"FeeAdt": 0,

"FeeChd": 0,

"FeeInf": 0,

"ServiceFeeAdt": 0,

"ServiceFeeChd": 0,

"ServiceFeeInf": 0,

"TotalNetPrice": 0,


"TotalPrice": 0,

"ListFlight": [

{

"FlightId": 0,

"Leg": 0,




"StartDate": "2019-05-30T08:15:26.738Z",

"EndDate": "2019-05-30T08:15:26.738Z",


"StopNum": 0,


"Duration": 0,

"NoRefund": true,



"Promo": true,


"ListSegment": [

{

"Id": 0,




"StartTime": "2019-05-30T08:15:26.738Z",

"EndTime": "2019-05-30T08:15:26.738Z",


"Duration": 0,

"Class": "string",

"Plane": "string",



"HasStop": true,


"StopTime": 0,

"DayChange": true,




"LastItem": true,


}

]

}

]

}

P a g e 24 | 38

}

],

"Status": true,


"Message": "string",

"Language": "string"

}

▪ Detail Description for Structure of response data:

Description of VerifyResponse

Field Name Required Description Data Type Example Status Connection result bool True

ErrorCode Error code (if availble) string

Message Error message (if avaibale) string

ListFareStatus List of flight status FareStatus

Description of FareStatus

Field Name Required Description Data Type

Status Check result: True – the flight is available. False – the flight is changed.

bool True

Remark Remark if the flight is changed string

Price Newest price double 1250000

Difference Difference if the price has been changed

double 0

Session Session for latest price data string

FareData The lastest update for the flight

FareData

Refer to the Description of FareData in Heading 1. Flights search

▪ Notes:

- API responses a list of checking result for each :

o If Status = OK: Flight and fare are valid.

o If Status = FAIL: Flight is no longer available or fare is changed

- Price: the newest fare for flight if this flight is valid.

- Difference: total amount for fare difference if fare has been changed

- FareData: The latest available price of the flight.

- Session: This is session token for latest price. Use this paramerter for booking in case

of price or flight has been changed.

P a g e 25 | 38

5. Booking

Introduction ▪ This function allows to book the flight on airlines system or GDS and then return booking

code (record locator), time limit, booking image... and other necessary fields .

▪ API is able to hold booking on:

- Airline’s Web agent : VJ, JQ, QH.

- Sabre system: VN.

- Galileo system: other international airlines.

- Other systems : optional.

▪ Datacom provides 3 booking methods in the API:

- Standard booking: Partner uses the flights and session ID returned from search

response to build booking request data.

✓ Advantage: Simple, accurate, and fastest.

✓ Disadvantage: Data of Session are available only in 180 minutes.

- Indirect booking: Partner transmits fields of itinerary, flight number, fare... Booking

Engine system of Datacom automatically search, compare and select to make

reservation.

✓ Advantage: Partner can use search database flexibly without dependence on

Datacom’s search Session.

✓ Disadvantage: Inaccurate flight data result in low successful reservation rate.

- Direct booking: partner transmits fields of itinerary, flight number, fare... Booking

Engine system of Datacom directly send these fields to airlines to make reservation.

✓ Advantage: Partner can use search database flexibly without dependence on

Datacom’s search Session, processing time is faster because flights don’t

rechecked and compared.

✓ Disadvantage: flight data are not accurate, not checked and not compared

that result in low successful reservation rate.

▪ Some suggested resources should be available for reservation via API:

- Sign in to book on domestic carriers.

- Sabre Sign In.

- PCC, online Client ID to access data on Galileo system.

- Datacom will support partner about booking reservation method during integrated

process

P a g e 26 | 38

5.1. Standard Booking

Description ▪ This function allows to reserve booking with flight fields from returned searching result of

API.

▪ Once flight searching is requested, Booking Engine system will save search result for each

session on Datacom’s server, Partner transmits the selected FareData, flight which Booking

engine system of Datacom then will search exactly and make a reservation.

▪ Max valid time for each search session to make reservation is 180 minutes.

Request ▪ URL: http://platform.datacom.vn/flights/book

▪ Method: POST

▪ Structure of request data: BookRequest

Description of BookRequest


BookType Yes Type of booking string book-normal

UseAgentContact Yes Contact of booking Agent

bool True

Contact Yes Contact Contact

ListPassenger Yes List of passenger Passenger[]

ListFareData Yes List of fare data FareDataInfo[]


Description of Contact


Gender Yes Title: True – Mr, False – Mrs/Ms

bool True

FirstName Yes First Name of Contact person

string TRAN

LastName Yes Last name of Contact person

string NGOC LINH

Phone Yes Phone number string 0912345678

Email Yes Email address string [email protected]

Address No Address of contact person

string Dong Da, Hanoi

Description of Passenger


Index Yes Order in Index int 0

FirstName Yes First Name string TRAN

LastName Yes Last Name and Middle Name

string NGOC LINH

Type Yes Passenger Type code ADT, CHD, INF

string ADT

Gender Yes Gender: True – male, False – female

bool True

Birthday Optional Date of Birth Format ddMMyyyy

string 15061988

ListBaggage No List of allowance baggage Baggage[]

Description of Baggage


http://platform.datacom.vn/flights/book

mailto:[email protected]

P a g e 27 | 38

Airline Yes Airlines code string VJ

Leg No Order of sector int 0

Route Yes Value of sector string HANSGN

Code Yes Code of baggage package string 15

Currency No Currency code string VND

Name No Name of baggage package string 15kg baggage

Price Yes Price for baggage package double 154.000

Value Yes Weight of baggage string 15kg

Description of FareDataInfo


Session Yes Session string DC0001HAN…

FareDataId Yes Fare Data ID int 15

AutoIssue Yes Auto book and issue this ticket

bool False

ListFlight Yes List of selected Flights FlightInfo[]

Description of FlightInfo


FlightValue Yes Value of flight string 1VJ123HAN…

▪ Notes: - FirstName, LastName of passenger must be Vietnamese without diacritic marks, No

Number, No special characters. Partner have to import exactly full name of

passenger. No test with offensive data (aaaaa, bbbb…).

- If UseAgentContact = True: Booking Engine system will retrieve the information

registered in agent account on Datacom system to make a reservation (Email, Phone,

Address).

- Contact fields such as Email, Phone, Address must be valid data, No test for offensive

data ([email protected], aaaa bbbb, 11112222…). These contact fields are used when

airlines need to inform all changes of flights. Thus it is recommended to transmit

information as exactly as possible.

- If parameter AutoIssue = true: System will reserve booking and instantly issue tickets

( paid by agency account) . Partner can use this function to instantly issue ticket in

cases of special fares, promotion fares, flights right before departure time, on LCC

with no permission for advanced reservation.

Important notice: When AutoIssue = true, real tickets will be issued and agency

account will be charged immediately.

- Please contact to our support department for any queries during integrated process.

Response ▪ Structure of response data: BookResponse

{

"BookingId": 0,

"ListBooking": [

{

"Status": "string",


"BookingCode": "string",

"GdsCode": "string",

"Flight": "string",

"Route": "string",


mailto:[email protected]

P a g e 28 | 38

"ErrorMessage": "string",

"BookingImage": "string",

"ExpiryDate": "2019-05-31T06:44:02.464Z",

"ResponseTime": 0,

"System": "string",

"Price": 0,

"Difference": 0,

"ListTicket": [

{

"Index": 0,


"TicketNumber": "string",

"IssueDate": "2019-05-31T06:44:02.464Z",


"PassengerName": "string",

"BookingFile": "string",

"TicketImage": "string",

"TotalPrice": 0,

"Status": "string",

"ErrorMessage": "string"

}

],


"FareData": {

"FareDataId": 0,


"Itinerary": 0,

"Leg": 0,

"Promo": true,


"System": "string",

"Adt": 0,

"Chd": 0,

"Inf": 0,

"FareAdt": 0,

"FareChd": 0,

"FareInf": 0,

"TaxAdt": 0,

"TaxChd": 0,

"TaxInf": 0,

"FeeAdt": 0,

"FeeChd": 0,

"FeeInf": 0,

"ServiceFeeAdt": 0,

"ServiceFeeChd": 0,

"ServiceFeeInf": 0,

"TotalNetPrice": 0,


"TotalPrice": 0,

"ListFlight": [

{

"FlightId": 0,

"Leg": 0,




"StartDate": "2019-05-31T06:44:02.464Z",

"EndDate": "2019-05-31T06:44:02.464Z",


"StopNum": 0,


"Duration": 0,

"NoRefund": true,



"Promo": true,


"ListSegment": [

P a g e 29 | 38

{

"Id": 0,




"StartTime": "2019-05-31T06:44:02.464Z",

"EndTime": "2019-05-31T06:44:02.464Z",


"Duration": 0,

"Class": "string",

"Plane": "string",



"HasStop": true,


"StopTime": 0,

"DayChange": true,




"LastItem": true,


}

]

}

]

}

}

],

"Status": true,


"Message": "string",

"Language": "string"

}

Description of BookResponse





BookingId Booking ID in Datacom System

int 9999999

ListBooking List of Booking Booking

Description of Booking


Status Booking Status OK: Successful FAIL: Error

string OK

Airline Airline code string VN

BookingCode Booking code on airlines string HWBGTD

GdsCode Booking code on GDS

Flight Flight information

Route Sector/segment information

ErrorMessage Error message (if available) string

BookingImage Mặt booking (Sabre) string

ExpiryDate Expired date DateTime

ResponseTime Response time (seconds) double 8.79

System Booking System string Sabre

Price Newest price double 1250000

Difference Difference if the price has been changed

double 0

Session Session for latest price data string

P a g e 30 | 38

FareData The lastest update for the flight

FareData

ListTicket List of ticket, returned if book and auto issue

Ticket[]

▪ Notes:

- API will be returned BookingId. This ID is used to access booking data on Datacom.

- API will be returned list of PNRs (Passenger Name Record):

o If Status = OK: Successful

o If Status = FAIL: unsuccessful

- BookingCode: PNR code on airlines system or GDS.

- GdsCode: Booking Code On GDS. Notes for GdsCode:

o All domestic and international flights on LCCs, the system does not

response GDScode

o All international flights on GDS: the system will response separate

BookingCode on each airlines and for separate segments. In case of

temporary disconnection between GDS ( Galileo) and airlines regarding to

retrieve BookingCode, API will response GDScode without BookingCode.

- Partner should check Error code, error message to know reasons why booking are

held unsuccessfully.

- BookingImage: are returned depending on airlines and booking system.

- System: Booking system

o lowcost: reservation on the web agents of LCCs.

o sabre: reservation for Vietnam airlines (VN) on Sabre system.

o galileo: reservation on GDS Galileo.

- ListTicket: If AutoTicket = True, API will be returned list of ticket.

- Flight: FlightValue for booking is called in FlightValue during booking request. For

return – flights, FlightValue is separated with characters like this:

o One Way: 0VJ163J_EcoHANSGN201907202010

o Return : 0VN163PHANSGN201907| 1VN172THANSGN2019072

- Route: Routes for booking are connected departure airport with arrival airport. For

return-flights, the routes are separated with characters like this:

o One way: HANSGN

o Return: HANSGN|SGNHAN

- FareData: The latest available price of the flight.

- Session: This is session token for latest price. Use this paramerter for booking in case

of price or flight has been changed.

P a g e 31 | 38

5.2. Indirect booking

Description ▪ In case of not using FareData, Flight from session on Server of the Booking Engine system,

Partner is able to transmit detail field of the flight partner want to book.

▪ Partner is able to get the details of flight from search results of Datacom or other sources.

The information need be correct with standard formats of airline operation.

▪ We will analyze, search, compare and make a reservation with your flights information.

▪ In this method, Booking Engine will actively search the existence of the flight and fare before

making a reservation in order to minimize the errors or result in low error rate.


▪ Method: POST


{

"BookType": "string",

"UseAgentContact": true,

"Contact": {

"Gender": true,

"FirstName": "string",

"LastName": "string",

"Phone": "string",

"Email": "string",

"Address": "string"

},

"ListPassenger": [

{

"Index": 0,



"Type": "string",

"Gender": true,

"Birthday": "string",

"ListBaggage": [

{


"Leg": 0,

"Route": "string",

"Code": "string",


"Name": "string",

"Price": 0,

"Value": "string"

}

]

}

],

"ListFlight": [

{

"AutoIssue": true,


"Leg": 0,




"DepartTime": "string",



"Price": 0,

"CompareMode": "string"

}

],


P a g e 32 | 38







}



BookType Yes Booking type: book-custom

string book-custom

UseAgentContact Yes Use agent contact when booking

bool True

Contact Yes Contact information Contact

ListPassenger Yes List of passengers Passenger[]

ListFlight Yes List of flight detail FlightDetail[]


Refer to Description of Contact, Passenger in the heading 4.1. Standard booking , Page

26.

Description of FlightDetail


Airline Yes Airline cdoe string VN

Leg Yes Order of sector int 0

StartPoint Yes Departure point code string HAN

EndPoint Yes Arrival point code string SGN

DepartDate Yes Departure date Format: ddMMyyyy

string 17092019

DepartTime Yes Departure time Format: HHmm

string 0800

FlightNumber Yes Flight number string VN179

FareClass Yes Fare class string M

Price Yes Prive double 299.000

CompareMode Yes Compare mode base, price, total

string base

AutoIssue Yes Auto issue bool False

▪ Notes: - Leg: Order of sector in the whole Itinerary. Departure sector: 0, return sector: 1, next

sectors: 2, 3,…

- CompareMode:

o base: compare by base fare of 01 Adult.

o price: compare by total fare ( base fare and taxes, fees ) of 01 Adult.

o total: compare by total fare ( base fare, taxes, fees of all passengers

(booking price).

- If AutoIssue = true: System will make a reservation and instantly issue ticket ( paid by

agency account) . For Promotion fares, flights right before departure time and LCCs

that are unable to hold booking, Partner is able to use this function to issue ticket

instantly.



P a g e 33 | 38

Response Refer to Description of BookResponse in Heading 4.1. Standard booking, page 27.

P a g e 34 | 38

5.3. Direct booking

Description ▪ In case of no using Fare Data, Flight from Session on the server of Booking Engine, Partner is

able to transmit detail information that partner want to book.

▪ The detail information are able to retrieved from Datacom’s Search results or other sources

which must be complied with standard formats of Airline’s operations.

▪ Booking Engine will request directly the flight information to booking system and make a

reservation with the loaded data.

▪ This method will ignore steps of checking, comparison for the existence of flights and fares.


▪ Method: POST


{

"BookType": "string",

"UseAgentContact": true,

"Contact": {

"Gender": true,



"Phone": "string",

"Email": "string",

"Address": "string"

},

"ListPassenger": [

{

"Index": 0,



"Type": "string",

"Gender": true,

"Birthday": "string",

"ListBaggage": [

{


"Leg": 0,

"Route": "string",

"Code": "string",


"Name": "string",

"Price": 0,

"Value": "string"

}

]

}

],

"ListFlight": [

{

"AutoIssue": true,


"Leg": 0,




"DepartTime": "string",



"Price": 0,

"CompareMode": "string"

}

],


P a g e 35 | 38







}



BookType Yes Booking types: book-direct

string book-direct

UseAgentContact Yes Use agent contact when booking

bool True

Contact Yes Contact information Contact

ListPassenger Yes List of passengers Passenger[]

ListFlight Yes List of flights FlightDetail[]


Refer to Description of Contact, Passenger Heading 4.1. Standard, page 26.

Description of FlightDetail


Airline Yes Airline code string VN

Leg Yes Order of sector int 0

StartPoint Yes Departure point code string HAN

EndPoint Yes Arrival point code string SGN

DepartDate Yes Departure date Format: ddMMyyyy

string 17092019

DepartTime Yes Departure time Format: HHmm

string 0800

FlightNumber Yes Flight number string VN179

FareClass Yes Fare class string M

Price Yes Price double 299.000

CompareMode No Compare mode string

AutoIssue Yes Auto issue bool False

▪ Notes: - Leg: Order of sector in the whole Itinerary. Departure sector: 0, return sector: 1, next

sectors: 2, 3,…

- Price: Input the base fare for 01 ADT.

- If AutoIssue = true: System will make a reservation and instantly issue ticket ( paid by

agency account) . For Promotion fares, flights right before departure time and LCCs

that are unable to hold booking, Partner is able to use this function to issue ticket

instantly .



Response Refer to Description of BookResponse in Heading 4.1. Standard booking, page 27.

P a g e 36 | 38

6. Issue ticket Description

▪ This function allows to issue tickets by the agency account on carriers and on GDS.

▪ Tickets are only issued for valid bookings, valid time limit, valid rules of advanced purchase.

▪ API is able to issue on :

- Domestic Carriers: VN, VJ, JQ, QH.

- Sabre system : Vietnam Airlines ( VN ).

- GDS Galileo : Participant international carriers.

- Other system : optional

▪ Some suggested resources should be available for reservation via API:

- Sign- in ID to issue tickets on domestic carriers.

- Contract, agreements to issue tickets on GDS Galileo and the suppliers.

- Datacom will support partner about ticketing method during integrated process

Request ▪ URL: http://platform.datacom.vn/flights/issue

▪ Method: POST

▪ Structure of request data: IssueRequest

{









}

Description of IssueRequest



BookingCode Booking code string HWBGTD

API Authentication Refer to: API Authentication

Response ▪ Structure of response data: IssueResponse

{

"ListTicket": [

{

"Index": 0,


"TicketNumber": "string",

"IssueDate": "2019-04-10T09:05:28.571Z",


"PassengerName": "string",

"BookingFile": "string",

"TicketImage": "string",

"TotalPrice": 0,

"Status": "string",

"ErrorMessage": "string"

}

],

http://platform.datacom.vn/flights/issue

P a g e 37 | 38


"Status": true,


"Message": "string"

}

▪ Specification of structure of response data

Description of IssueResponse


Status Connection results bool True



BookingImage Booking Image string

ListTicket List of Ticket Ticket

Description of Ticket


Index Order Number string 0


TicketNumber Ticket number string 7381234568975

IssueDate Issue time/date DateTime


PassengerName Name of passengers string TRAN/NGOC…

BookingFile Fields of booking string

TicketImage Ticket image string

TotalPrice Total price double 1.850.000

Status Ticket status string OPEN

ErrorMessage Error message (if available) string

▪ Notes:

- This method returns data of booking image and list of tickets.

- If Status = True and List of Tickets (ListTicket) contains data: issue ticket successfully.

- If Status = False and List of Tickets (ListTicket) is empty: issue ticket unsuccessfully.

- Partner should check error code, error message to find causes of unsuccessful issue.

- For bookings on Vietnam Airlines or on other airlines on GDS, ticket List will return

the corresponding number of passengers on booking, including ticket numbers and

passenger names.

- For bookings on the carriers VJ, JQ, QH: Ticket list will return one single code which is

right Booking code, because these carriers don’t return any other ticket numbers like

VN, GDS.

- Returned data or information may be different based on each specific airline’s terms,

conditions or characteristics.

P a g e 38 | 38

7. Booking Management

7.1. Void ticket

Description ▪ This function allow to void issued tickets and cancel booking.

▪ This function is currently available for Vietnam Airlines (VN).

▪ Condition to void: applied for tickets just issued during the day and before closing time of

report (usually before 23:00).

Request ▪ URL: http://platform.datacom.vn/flights/void

▪ Method: POST

▪ Structure of request data: VoidRequest

{



"CancelBooking": true,







}

Description of VoidRequest


Airline Airline number string VN


CancelBooking Cancel booking bool True

API Authentication Refer to: API Authentication

▪ Notes:

- Set CancelBooking = true if partner need to cancel itinerary on booking.

Response ▪ Structure of response data: VoidResponse

{


"Status": true,


"Message": "string"

}

Description of VoidResponse





BookingImage booking image string

▪ Noted:

- If Status = True: Void tickets successfully

- Nếu Status = False: Void tickets unsuccessfully

- Partner should check error code, error message to find causes of unsuccessful void.

- When BookingImage is returned, partner should recheck Void status on the tickets to

prevent error cases.

http://platform.datacom.vn/flights/void

api integration documentation - datacom · 2019-05-31 · p a g e 4 | 38 1. search flights...

Documents