Tài liệu tích hợp vé máy bay


Mục lục


© 2018 NLAB.VN | Công ty TNHH NLAB
Địa chỉ: Số 11 Thái Hà, Đống Đa, Hà Nội

Giới thiệu

NLAB chúng tôi với những chuyên gia trong ngành công nghệ thông tin và tự động hóa, đã phát triển thành công công cụ trợ giúp khách hàng tìm vé và đặt giữ chỗ tự động. Với đại lý du lịch thì đây là công cụ không thể thiếu. Với khách hàng, nó cho phép có cái nhìn tổng quan về các chặng bay mà họ quan tâm. Dễ dàng so sánh và giữ chỗ.

Công cụ của chúng tôi hiện tại là công cụ đơn giản nhất và nhanh chóng nhất để đại lý có được một website đặt vé. Chúng tôi có đủ mã nhúng cho tới plugin giúp bạn triển khai gần như trong một tiếng là có website đặt giữ chỗ tự động.

Ngoài ra, công cụ nội bộ của chúng tôi cấp cho đại lý còn có những tool vô cùng hấp dẫn như đặt lại vé, tìm lại hành trình, chase vé, theo dõi hoạt động tìm kiếm, thống kê vé đã đặt ...

Mục đích tối thượng của chúng tôi là tự động mọi thứ. Đại lý mất ít thao tác nhất để giữ được chỗ, năng suất lao động tăng.

Được thiết kế bởi chuyên gia UI và UX, chúng tôi là một trong những nhà cung cấp dịch vụ thiết kế website vé máy bay số 1 tại Việt Nam.

*CODER VIẾT DOCUMENT KHÔNG TỐT, VÌ THẾ NẾU CÓ SAI SÓT, HÃY ĐÓNG GÓP Ý KIẾN ĐỂ CHÚNG TÔI SỬA ĐỔI !

Đăng ký tài khoản và cài đặt

Tất cả các thông tin quản trị, đăng ký và cài đặt đều nằm trên https://apimaybay.com !

Việc đăng ký và kích hoạt là hoàn toàn tự động. Bạn chỉ cần có email đang hoạt động được và đang nhận được email. Tốt hơn hết là bạn dùng Gmail vì lý do bảo mật và có thể nhận email kích hoạt của chúng tôi !

Để tài khoản hoạt động, bạn truy cập vào phần cài đặt trên công cụ APIMAYBAY.COM, cài đặt giá, tài khoản hold chỗ và một vài thông tin khác.

Kết nối chúng tôi với CRM hoặc nguồn ngoài

Nhằm khoa học nhất sự quản lý của phòng vé, đáp ứng hầu hết nhu cầu của các phòng vé bận rộn. Chúng tôi có mở cổng để kết nối ra ngoài bao gồm:

  • Cổng CRM POST Json sang CRM của khách hàng
  • Cổng SLACK dành cho những phòng vé sử dụng SLACK

Tất cả các kết nối mời bạn truy cập APIMAYBAY.COM và chọn phần Cài đặt > Kết nối.

Dành cho những người sử dụng Wordpress

Hiện tại, Wordpress được rất nhiều người yêu thích sử dụng do có kho giao diện miễn phí và đẹp. Chưa kể cộng đồng Wordpress rất đông đảo nên bạn dễ dàng nhận được sự hỗ trợ của họ ! Chúng tôi cũng dành rất nhiều thời gian để phát triển một plugin cơ bản cho Wordpress. Giúp các doanh nghiệp / phòng vé nhanh chóng triển khai website bán vé máy bay trong nháy mắt.

Các bạn có thể tải về sau khi đăng ký tài khoản !

Sử dụng mã nhúng

Mã nhúng là một trong những thế mạnh của NLAB. Bạn có thể sử dụng mã nhúng trong các trường hợp:

  1. Website hosted tại Blogger, Wordpress.com, Wix và không thể cài thêm plugin
  2. Website sử dụng mã nguồn khác chưa có plugin như DotNET, JOOMLA, DRUPAL, Magento hay React

Ưu điểm là thao tác nhanh, chỉ vài thao tác thêm thẻ đơn giản là bất kỳ ai cũng có thể triển khai được !

Triển khai mã nhúng

Đầu tiên, bạn thêm mã javascript sau vào trước thẻ đóng </head> của website:

<script>
	 var ProductKey = "PRODUCTKEY_CUABAN";
	 (function () {
	 var A = document.createElement("script");
	 A.type = "text/javascript"; A.async = true;
	 A.src = "https://apimaybay.com/embed_v2/embed.js?version=56";
	 var s = document.getElementsByTagName("script")[0];
	 s.parentNode.insertBefore(A, s);
	 })();
</script>
						

Trong đó: PRODUCTKEY_CUABAN chính là mã Productkey trong phần cài đặt, bạn có thể truy cập APIMAYBAY.COM, tìm phần cài đặt > Security Code ! Mã này sinh ra để phân biệt bạn với những người dùng khác và độc nhất.

Quy định nơi hiển thị kết quả tìm kiếm

Chọn một trang hiển thị kết quả, ví dụ bạn tạo trang không có nội dung domain.com/tim-ve sau đó thêm thẻ sau:

<div id="show_flights"> </div>
Quy định nơi hiển thị ô tìm vé

Để hiển thị ô tìm vé, bạn cần đặt thẻ sau đây ở trang chủ hoặc bất cứ nơi nào bạn muốn hiển thị:

<div data-url="YOUR_URL" id="show_searchbox"> </div>

Trong đó YOUR_URL chính là URL trang để hiển thị kết quả mà bạn đã cài trước đó. Tất thảy các tiến trình đều được xử lý tự động và hiển thị ngay !

Sử dụng API

Tài khoản cần được set-up riêng nên bạn không thể sử dụng tài khoản đăng ký để query tới API của chúng tôi ! Những khách hàng có nhu cầu vui lòng email tới địa chỉ email của công ty sau khi đăng ký tài khoản trên APIMAYBAY.COM

[Nếu] tài khoản của bạn không được cài đặt để sử dụng API, bạn vẫn sử dụng được [với điều kiện] phải thêm thư viện đặc biệt của chúng tôi vào và chỉ được hiển thị trên Web mà không sử dụng được trong ứng dụng. Bạn thêm thư viện sau đây:

<script src="https://apimaybay.com/embed_v1/js/rat-trap.js"> </script>

Thư viện tự sinh ra rất nhiều cookie, bạn sẽ đính kèm các biến có bắt đầu bằng nlabvn_* vào trong mọi request tới API. cụ thể bạn cần đính kèm:

security_code	MÃ Security của bạn
host	lấy từ cookie nlabvn_host
hash	lấy từ cookie nlabvn_hash
cat	lấy từ cookie nlabvn_cat
handAjax	lấy từ cookie nlabvn_handAjax
handSocket	lấy từ cookie nlabvn_handSocket
handWebsocket	lấy từ cookie nlabvn_handWebsocket
verified	lấy từ cookie nlabvn_verified
stamp	lấy từ cookie nlabvn_stamp

Những ai sẽ cần tới API ?

  1. Build riêng hệ thống để custom tối đa theo ý thích
  2. Viết APP cho điện thoại di động
  3. Viết phần mềm cho máy tính để bàn
  4. Hệ thống khác cần một hệ thống backup
Triển khai API

Hoạt động của API là realtime và dữ liệu đổ về realtime, cho nên bạn cần hiểu cơ chế của chúng để yêu cầu / lấy dữ liệu về một cách chính xác

Tiến trình: TẠO Phiên tìm kiếm > Lấy kết quả đổ về realtime > Lấy mã ID của chuyến để Book > Đợi book đổ về PNR / thời gian giữ chỗ

Lưu ý chung

  • Tất cả yêu cầu đều là POST với kiểu application/x-www-form-urlencoded thông thường.
  • Dữ liệu trả về luôn luôn là JSON application/json; charset=utf-8
  • Không Cookie, không cấm IP query, bắt buộc mọi request đều chứa security code ( được cấp trong APIMAYBAY.COM > Cài đặt > Security Code )
  • Với các tài khoản thông thường, nếu dùng API sẽ phải kèm theo thư viện chung, tự thư viện chung sinh ra các cookie, bạn sẽ lấy cookie này gửi đính kèm mọi request từ đây về sau. Thực ra chúng tôi không dùng các biến này trong một số bước, tuy nhiên về mặt kỹ thuật, luôn đính kèm thì dễ triển khai hơn.

Bước 1: Khởi tạo Session tìm kiếm:

Mục đích: Khởi tạo session để các con robots đi dò tìm dữ liệu cho phiên làm việc của bạn. Nó sẽ trả về error nếu lỗi, nếu hợp lệ, nó trả về một mã trong trường results

Request URL:https://api.nlab.vn/search
Request method:POST
Form data:
	from:	HAN
	to:	SGN
	depart:	18/05/2019
	return:	false
	adt:	1
	chd:	0
	inf:	0
	security_code: MÃ CỦA BẠN !
						

Trong đó, như đã nói ở trên, với tài khoản set-up dùng API thì các trường sau đây không bắt buộc, còn nếu không, bạn sẽ phải đính kèm các trường: host, hash:, cat, handAjax, handSocket, handWebsocket, verified, stamp được lấy trong cookie do thư viện chung sinh ra với tiền tố đính kèm nlabvn_***

Ý nghĩa các trường:

  1. from -> đi từ đâu ( mã IATA 3 ký tự hợp lệ )
  2. to -> đến đâu ( mã IATA 3 ký tự hợp lệ )
  3. depart -> ngày đi ( phải đúng định dạng dd/mm/yyyy )
  4. return -> ngày về, false nếu một chiều
  5. adt -> số người lớn
  6. chd -> số trẻ em
  7. inf -> số em bé ( không được lớn hơn số người lớn )
  8. security_code -> mã bảo mật của bạn, bạn luôn đính kèm trong mọi truy vấn !

Dữ liệu trả về mẫu:

JSON: 	
	error	""
	status	OK
	results	201944RH34m6RDSmBD
						

Trong đó:

  1. error -> thông báo lỗi nếu xảy ra
  2. status -> trạng thái lệnh, thường vẫn là OK
  3. results -> mã sinh ra để bạn thực hiện bước sau. Rỗng nếu có lỗi !
Bước 2: Nhận kết quả đổ về

Kết quả đổ về ở một đường dẫn khác. Các bạn truy vấn như sau:

Request URL:https://api.nlab.vn/get_results
Request method:POST

Các trường dữ liệu:

hash_code	201944RH34m6RDSmBD ( lấy ở trường results của bước khởi tạo session )
security_code	Mã của bạn
						

Kết quả trả về biến động liên tục do dữ liệu từ các con robots được đổ về đây. Bạn sẽ truy vấn nhắc lại sau mỗi giây cho tới khi có đủ các hãng hoặc cho tới khi trường status trả về true. Thường thì sau 30 giây, dù truy vấn thiếu hay đủ vẫn phải dừng lại !

Kết quả trả về mẫu:

{"error":"","status":true,"results":{"QH":{"BestInWeek":{"outbound":{"23-05":820900,"24-05":820900,"25-05":820900,"26-05":820900,"27-05":820900,"28-05":820900,"29-05":820900},"inbound":[]},"OutBound":[{"ID":"QH1971","Class":"Eco","Duration":"02h 10m","Flight":{"Class":"Eco","BrandCode":"QH","BrandName":"Bamboo Airways","Transit":0,"Number":"QH1971","Aircraf":"Airbus A319","Duration":"02h 10m","Departure":"11:50 26-05-2019","Arrival":"14:00 26-05-2019","Origin":"VDO","Destination":"SGN"},"Flights":[{"Class":"Eco","BrandCode":"QH","BrandName":"Bamboo Airways","Transit":0,"Number":"QH1971","Aircraf":"Airbus A319","Duration":"02h 10m","Departure":"11:50 26-05-2019","Arrival":"14:00 26-05-2019","Origin":"VDO","Destination":"SGN"}],"Prices":{"AdultFare":399000,"AdultFee":421900,"ChildFare":299250,"ChildFee":351925,"InfFare":100000,"InfFee":10000}}],"InBound":[]},"BL":{"id":"2019448cMrVkhCovvh","error":"","status":true,"OutBound":[],"InBound":[],"BestInWeek":{"inbound":{},"outbound":{}}},"VJ":{"id":"2019448cMrVkhCovvh","OutBound":[{"ID":"VJ231","Class":"Promo","Flight":{"Class":"Promo","BrandCode":"VJ","BrandName":"VietJet Air","Transit":0,"Number":"VJ231","Aircraf":"A320","Duration":"02:15","Departure":"09:50 26-05-2019","Arrival":"12:05 26-05-2019","Origin":"VDO","Destination":"SGN"},"Flights":[{"Class":"Promo","BrandCode":"VJ","BrandName":"VietJet Air","Transit":0,"Number":"VJ231","Aircraf":"A320","Duration":"02:15","Departure":"09:50 26-05-2019","Arrival":"12:05 26-05-2019","Origin":"VDO","Destination":"SGN"}],"Prices":{"AdultFare":199000,"AdultFee":422900,"ChildFare":199000,"ChildFee":363900,"InfFare":0,"InfFee":110000,"Class":"Promo","total_fare":218900,"total_fee":350000,"total_all":591900}}],"InBound":[],"BestInWeek":{"outbound":{"05-05":1061900,"06-05":621900,"07-05":621900,"08-05":621900,"09-05":621900,"10-05":621900,"11-05":621900,"12-05":621900,"13-05":621900,"14-05":621900,"15-05":621900,"16-05":621900,"17-05":621900,"18-05":621900,"19-05":621900,"20-05":621900,"21-05":621900,"22-05":621900,"23-05":621900,"24-05":621900,"25-05":621900,"26-05":621900,"27-05":621900,"28-05":621900,"29-05":621900,"30-05":621900,"31-05":621900},"inbound":{}}},"VN":{"OutBound":[{"ID":"VN 1287","Class":"E","Duration":"02:05","Prices":{"AdultFare":1050000,"AdultFee":385000,"ChildFare":945000,"ChildFee":334500,"InfFare":105000,"InfFee":160500},"Flight":{"Class":"E","BrandCode":"VN","BrandName":"Vietnam Airlines","Transit":0,"Number":"VN 1287","Aircraf":"321","Duration":"02:05","Departure":"15:45 26-05-2019","Arrival":"17:50 26-05-2019","Origin":"VDO","Destination":"SGN"},"Flights":[{"Class":"E","BrandCode":"VN","BrandName":"Vietnam Airlines","Transit":0,"Number":"VN 1287","Aircraf":"321","Duration":"02:05","Departure":"15:45 26-05-2019","Arrival":"17:50 26-05-2019","Origin":"VDO","Destination":"SGN"}]}],"InBound":[],"BestInWeek":{"outbound":{"23-05":939000,"24-05":3250000,"25-05":939000,"26-05":1435000,"27-05":939000,"28-05":939000,"29-05":939000},"inbound":[]}}}}
						

Dữ liệu đổ về rất dài và khá phức tạp. Bạn nên tham khảo qua thư viện trong BAREBONE chúng tôi cấp phát để hiểu thêm. Trong đó một vài trường quan trọng cần hiểu thêm gồm:

  1. outbound: chứa các chuyến chiều đi
  2. inbound: các chuyến chiều về
  3. BestInWeek: Giá vé cả tuần của một hãng
  4. FlightFlights chứa thông tin chuyến bay, nhưng Flight để hiển thị chung, còn Flights hiển thị chi tiết chuyến bay gồm hay không gồm các chuyến bay nối chuyến
  5. Prices là trường chứa giá, giá khách thanh toán là giá FARE + Thuế phí, ví dụ Số người lớn x ( AdultFare + AdultFee ) = giá vé cuối cùng

Bước 3: Hold chỗ

Hold chỗ cần thông tin chuyến bay và thông tin khách hàng, thông tin liên hệ. Nếu mọi thứ hợp lệ, nó trả về một mã session để bạn có thể theo dõi mã PNR nếu cần. Hoặc không thì chỉ cần có mã trả về trong trường results nghĩa là hold chỗ đã được lưu vào cơ sở dữ liệu để bạn theo dõi trên APIMAYBAY.COM

Lúc này, bạn sẽ có hai trường hợp: Chuyển khách hàng tới trang thanh toán ngay hoặc đợi ra mã PNR ( mã giữ chỗ hàng không ) rồi chuyển khách sang trang thanh toán. Việc giữ chỗ diễn ra trong nền và đổ kết quả về một đường dẫn khác.

Truy vấn mẫu:

Request URL:https://api.nlab.vn/book
Request method:POST
form data:
	hash_code:	( lấy ở bước khởi tạo session )
	flights: {"outbound":"[QH]QH1971_Eco-399000"}
	passengers:	[{"type":"ADT","gender":"mrs","firstname":"NGUYEN","lastname":"NHU ANH","luggage":{"outbound":"15-160000","inbound":"0-0"}},{"type":"CHD","gender":"mr","firstname":"NGUYEN","lastname":"VAN QUYET","birthday":"02/02/2016","luggage":{"outbound":"40-465000","inbound":"0-0"}},{"type":"INF","gender":"ms","firstname":"PHUONG","lastname":"TUYET LINH","birthday":"02/02/2018"}]
	contact:	{"fullName":"NGUYEN QUANG HIEN","firstname":"NGUYEN","lastname":"QUANG HIEN","numberphone":"0906111180","email":"mcjambi@gmail.com","require":"","PaymentMethod":"default"}
	security_code:	MÃ CỦA BẠN
						

Trong đó:

  1. Các trường trên đều dùng chuỗi ( string ) chứ không phải json để post lên. Bạn có thể dùng hàm json_encode hoặc JSON.stringify để tạo chuỗi này từ mảng ( array )
  2. flights là trường chứa các chuyến bay, gồm outbound là chiều đi và inbound là chiều về nếu có.
  3. [QH]QH1971_Eco-399000 nghĩa là [BrandCode]Number_Class-AdultFare, từ danh sách chuyến bay, khách hàng chọn chuyến nào chúng ta sẽ format như vậy để book. AdultFare để căn cứ chuyến bay tăng giá hay chưa.
  4. Trường type trong passengers nhận 3 giá trị: ADT - người lớn, CHD - trẻ em, INF - em bé. Riêng trẻ em và em bé thêm trường birthday với format dd/mm/YYYY
  5. Trường gender nhận giá trị là MR hoặc MRS
  6. Trường luggage là hành lý của người bay, cấu trúc [Số kg hành lý ]-[Số tiền hành lý] được lấy từ file Luggage.json. Tại đó sẽ có số KG tương ứng với từng nhà bay và giá của từng gói tương ứng. Bạn cũng có thể bỏ số tiền và chỉ POST lên số KG cũng hợp lệ.
  7. Với trường contact, emailrequire có thể bỏ trống. PaymentMethod là cách thanh toán cũng có thể bỏ trống. Nếu có yêu cầu gì của khách có thể input vào trường require

Nếu mọi thứ hợp lệ, kết quả trả về:

error	""
status	true
results	201944nz9540DcQZiv
						

Bạn sẽ sử dụng mã trong trường results để thực hiện bước chờ PNR ở bước sau ! Còn nếu có bất kỳ lỗi phát sinh nào, hệ thống sẽ trả về trong trường error như thông thường !

Bước 4: Query PNR

Mã PNR sẽ được thực hiện trong nền, nên bạn có thể cho hiển thị mã hoặc chuyển khách tới trang thanh toán. Sau đây là truy vấn PNR mẫu:

Request URL:https://api.nlab.vn/pnr
Request method:POST
form-data:
	session_id	(Lấy ở bước trước đó)
	security_code	MÃ CỦA BẠN
						

Kết quả trả về:

{"error":"","status":true,"results":{"outbound":[{"error":"","deadline":"2019-05-05 02:03:00","pnr":"FVDUXY"},{"error":"","deadline":"2019-05-05 02:03:00","pnr":"FVDUXY"}],"inbound":[]}}
						

Trong đó:

  1. PNR: Mã giữ chỗ của hãng bay trả về
  2. Deadline: trường thời gian giữ chỗ hợp lệ
  3. outbound là của chiều đi, inbound là chiều về
  4. Nếu bất kỳ lỗi gì, hệ thống trả về tại trường error

LƯU Ý: Bạn nên hỏi lại sau mỗi giây cho tới khi nào có mã PNR hoặc sau 3 phút thì timeout. Bởi tiến trình được thực hiện trong nền và đổ về hệ thống nên phải truy vấn giống như lấy kết quả chuyến bay ở bước trên.

Trường session_id được trả về từ bước 3 còn được dùng để truy vấn lại booking, tham khảo bước sau đây:

Bước 5: Truy vấn Booking Info

Ở các bước giỏ hàng, hoặc bước cuối trong lúc thanh toán, bạn chỉ dựa vào mã session_id có thể truy vấn ngược lại toàn bộ thông tin của Booking vừa tạo. Booking này sẽ không thể truy vấn trong thời gian quá 7 ngày vì lý do bảo mật.

Truy vấn mẫu:

Request URL:https://api.nlab.vn/booking_info
Request method:POST
form-data:
	session_id	(Lấy ở bước trước đó)
	security_code	MÃ CỦA BẠN
						

Nếu hợp lệ, kết quả trả về như sau:

{
    "error": "",
    "status": true,
    "results": {
        "ID": 28059,
        "session_id": "201944NDC1VvkzCVtn",
        "search": "{\"timestamp\":1556953459,\"id\":\"201944NDC1VvkzCVtn\",\"origin\":\"HPH\",\"destination\":\"SGN\",\"depart\":\"26/05/2019\",\"return\":false,\"adt\":1,\"chd\":0,\"inf\":0}",
        "passengers": "[{\"type\":\"ADT\",\"gender\":\"MR\",\"firstname\":\"NGUYEN\",\"lastname\":\"VAN PHUONG\",\"luggage\":{\"outbound\":\"undefined-undefined\",\"inbound\":\"undefined-undefined\"}}]",
        "flights": "{\"outbound\":{\"ID\":\"VN 1193\",\"Class\":\"T\",\"Duration\":\"02:05\",\"Prices\":{\"AdultFare\":1550000,\"AdultFee\":525000,\"ChildFare\":1395000,\"ChildFee\":449500,\"InfFare\":155000,\"InfFee\":165500},\"Flight\":{\"Class\":\"T\",\"BrandCode\":\"VN\",\"BrandName\":\"Vietnam Airlines\",\"Transit\":0,\"Number\":\"VN 1193\",\"Aircraf\":\"321\",\"Duration\":\"02:05\",\"Departure\":\"20:35 26-05-2019\",\"Arrival\":\"22:40 26-05-2019\",\"Origin\":\"HPH\",\"Destination\":\"SGN\"},\"Flights\":[{\"Class\":\"T\",\"BrandCode\":\"VN\",\"BrandName\":\"Vietnam Airlines\",\"Transit\":0,\"Number\":\"VN 1193\",\"Aircraf\":\"321\",\"Duration\":\"02:05\",\"Departure\":\"20:35 26-05-2019\",\"Arrival\":\"22:40 26-05-2019\",\"Origin\":\"HPH\",\"Destination\":\"SGN\"}]},\"inbound\":\"\"}",
        "contact": "{\"fullName\":\"NGUYEN QUANG HIEN\",\"firstname\":\"NGUYEN\",\"lastname\":\"QUANG HIEN\",\"numberphone\":\"0906111180\",\"email\":\"mcjambi@gmail.com\",\"require\":\"\",\"PaymentMethod\":\"OFFICE\"}",
        "total_pay": 2075000,
        "booking_condition": "CONFIRMED",
        "_date": "2019-05-04 14:04:33"
    }
}
						

Bạn có thể hiển thị Booking lại bất kỳ khi nào khách hàng cần, hoặc để phù hợp với thiết kế của website.

Barebone cho nhà phát triển

Hiện tại barebone đang được hoàn thiện và sẽ sớm để download !