Tích hợp API đặt vé máy bay: những điều tài liệu không nói

Thẻ công việc trên board ghi "thêm vé máy bay". Bạn đã từng tích hợp cổng thanh toán, tính phí vận chuyển, có thể cả bản đồ, và mô hình bạn mang theo là mô hình hiển nhiên nhất: tìm kiếm, hiện kết quả, trừ thẻ, xong. Rồi lượt đặt chỗ thật đầu tiên trả về một mức giá khác với trang kết quả, lượt thứ hai bị timeout và không ai nói được khách đã có ghế hay chưa, và ai đó bên vận hành hỏi tại sao có đặt chỗ mà không có vé. Tích hợp API đặt vé máy bay nhìn từ ngoài giống một trang checkout thương mại điện tử. Bên dưới, đó là một giao dịch phân tán với những hệ thống được thiết kế từ rất lâu trước REST, và phần lớn bất ngờ đến từ khoảng cách đó.
Bài này viết cho lập trình viên chưa từng thấy một PNR. Nó không nói về endpoint của riêng nhà cung cấp nào; tên gọi thay đổi giữa các nhà cung cấp, còn hình dạng thì không.
Trình tự gọi API trong tích hợp API đặt vé máy bay
Gần như mọi API vé máy bay, dù đặt tên phương thức thế nào, đều đi qua bốn bước giống nhau. Vạch đúng ranh giới giữa các bước là phần lớn công việc.
| Bước | Bạn nhận được gì | Bạn phải lưu gì | Điều gì có thể sai |
|---|---|---|---|
| Tìm kiếm | Hành trình kèm giá và một khóa ưu đãi hay khóa giá vé không đọc được | Không gì lâu dài — kết quả cũ đi rất nhanh | Coi giá là giá cuối; khóa hết hạn trước khi thanh toán |
| Kiểm giá / xác minh | Giá đã xác nhận, điều kiện giá vé, hành lý, đôi khi các trường hành khách bắt buộc | Ưu đãi đã xác minh và thời hạn của nó | Giá đổi; hạng đặt chỗ hết; điều kiện khác với những gì bạn đã hiển thị |
| Đặt chỗ | Một đặt chỗ — PNR — với mã đặt chỗ và hạn xuất vé | Mã tham chiếu của riêng bạn, mã đặt chỗ, hạn xuất vé, dữ liệu hành khách đúng như đã gửi | Timeout không có phản hồi; PNR trùng; tên bị từ chối |
| Xuất vé | Số vé điện tử đã phát hành; đây là lúc tiền thực sự được cam kết | Từng số vé, gắn với hành khách và chặng tương ứng | Xuất vé một phần; hãng hủy đặt chỗ vì quá hạn |
Dòng bị tranh cãi nhiều nhất là dòng thứ ba, vì nhiều API cho phép đặt chỗ và xuất vé trong một lần gọi. Cứ dùng nếu bạn muốn. Nhưng trong thế giới của hãng bay, hai việc đó vẫn tách biệt: PNR có thể tồn tại mà không có vé, và việc xuất vé có thể thất bại sau khi PNR đã được tạo. Endpoint gộp chỉ che đi khoảnh khắc một bên thành công còn bên kia thì không, nên mô hình dữ liệu của bạn vẫn cần chỗ cho trạng thái đó.
Để ý cả điều mà tìm kiếm không trả về: một lời hứa. Nó là quảng cáo. Bước kiểm giá mới là báo giá, và chỉ có vé mới là giao dịch bán.
Vì sao giá tìm thấy không phải giá bạn đặt được
Lập trình viên web chờ đợi một danh mục sản phẩm. Kho ghế của hãng bay không phải vậy. Một chuyến bay được bán theo các hạng đặt chỗ, mỗi hạng là một thùng ghế ở một mức giá, và hãng liên tục mở, đóng các thùng này khi máy bay dần kín chỗ. Kết quả tìm kiếm được ghép rất nhanh từ dữ liệu chỗ trống có thể đã chậm một chút; đến lúc người dùng gõ xong hai hộ chiếu, hạng rẻ nhất trên chuyến đó có thể đã đóng. Bước kiểm giá hỏi lại, và câu trả lời trung thực đôi khi cao hơn.
Thuế cũng tự dịch chuyển. Thuế được tính lại khi kiểm giá cho đúng hành khách và hành trình, và trẻ em hay em bé có giá khác người lớn mà lượt tìm kiếm đã giả định. Nếu cửa hàng của bạn hiển thị bằng đồng trong khi nhà cung cấp báo giá bằng một đồng tiền khác, quy đổi ngoại tệ là thêm một chỗ khiến con số thay đổi.
Hệ quả về thiết kế rất đơn giản và hay bị bỏ qua: đừng bao giờ thu tiền theo giá tìm kiếm. Chạy bước kiểm giá trước khi thanh toán, so sánh, và nếu số tiền thay đổi thì hiện con số mới và hỏi khách. Phần markup bạn cộng thêm phải được tính lại trên giá mới, không mang nguyên từ trang kết quả — logic giống hệt điều một đại lý phải nghĩ khi xây dựng chiến lược markup trực tuyến, và nó gãy theo cùng một cách khi mức giá gốc bên dưới dịch chuyển.
Idempotency, và timeout lúc đặt chỗ nghĩa là gì
Phần này nên đọc hai lần.
Khi lời gọi đặt chỗ bị timeout, bạn không biết chuyện gì đã xảy ra. Yêu cầu có thể chưa bao giờ đến nơi. Có thể đã đến và thất bại. Hoặc — trường hợp đau nhất — nó đã đến, nhà cung cấp đã tạo PNR với hãng bay, và phản hồi bị mất trên đường quay về. Với code của bạn, cả ba trông như nhau. Với hãng bay, trường hợp thứ ba là một đặt chỗ đang sống, giữ ghế dưới tên khách hàng của bạn.
Phản xạ từ các tích hợp khác là thử lại. Ở đây, thử lại mù quáng có thể tạo ra PNR thứ hai cho cùng hành khách trên cùng chuyến bay. Các hãng coi đặt chỗ trùng là vi phạm chính sách; tùy hãng và thỏa thuận của đại lý, hậu quả có thể từ việc tự động hủy một hoặc cả hai đặt chỗ đến một thông báo ghi nợ — ADM — gửi cho bên đã xuất. Đại lý nhận được nó sẽ muốn biết vì sao hệ thống của bạn đặt hai lần.
Những gì hiệu quả, đại khái theo thứ tự sau:
- Tạo mã tham chiếu đặt chỗ của riêng bạn trước khi gọi ra ngoài, lưu lại, và gửi kèm yêu cầu ở mọi nơi API chấp nhận mã tham chiếu phía client. Nếu API hỗ trợ idempotency key, hãy dùng; nếu không, mã của bạn vẫn là thứ giúp tìm lại đặt chỗ sau đó.
- Mô hình hóa rõ ràng trạng thái "chưa rõ". Đang chờ, đã xác nhận, thất bại — và chưa rõ. Timeout chuyển đặt chỗ sang chưa rõ, không phải sang thất bại.
- Giải quyết trạng thái chưa rõ bằng cách hỏi, không phải bằng cách lặp lại. Truy xuất theo mã tham chiếu của bạn, hoặc liệt kê các đặt chỗ gần đây của những hành khách đó, trước khi quyết định có thử lại hay không.
- Chạy một job đối soát quét mọi thứ vẫn còn chưa rõ, so với những gì nhà cung cấp báo cáo, và chuyển phần không tự giải quyết được sang hàng đợi cho con người thay vì đoán.
Timeout lúc xuất vé là cùng vấn đề nhưng có dính tiền. Nếu bạn trừ thẻ trước khi xuất vé và việc xuất vé treo, bạn có một khách đã trả tiền và có thể không có vé. Nếu bạn xuất vé trước khi trừ tiền và việc trừ tiền thất bại, bạn đã phát hành một chứng từ mà ai đó phải trả cho hãng bay. Cách phổ biến là ủy quyền thẻ trước, xuất vé, rồi mới capture khi thành công — điểm mấu chốt là quyết định có chủ đích, không phải phát hiện ra trên production.
Những khái niệm hàng không khiến lập trình viên web bất ngờ
Không cái nào khó. Mỗi cái đều từng khiến ai đó mất một tuần chỉ vì không biết nó tồn tại.
PNR không phải là vé
PNR là hồ sơ đặt chỗ: hành khách, chặng bay, liên hệ, hạn xuất vé. Vé là chứng từ đã thanh toán cho phép hành khách bay. PNR chưa xuất vé sẽ hết hạn đúng hạn xuất vé và ghế được trả lại để bán, đôi khi lặng lẽ từ phía bạn.
Tên gần như không thể sửa
Sau khi xuất vé, phần lớn loại giá không cho đổi tên ngoài một chỉnh sửa nhỏ, và thế nào là nhỏ thì mỗi hãng một quy định. Tên phải khớp giấy tờ đi lại. Thu họ và tên riêng tách biệt — với tên tiếng Việt, đừng tự ý đảo thứ tự mà hãy theo đúng hộ chiếu — đừng để danh xưng từ ô văn bản tự do lọt vào trường tên, và kiểm tra trước lời gọi đặt chỗ, không phải sau.
Loại hành khách có giá, không phải để trang trí
Người lớn, trẻ em và em bé là các loại giá vé, và độ tuổi quyết định thường là tuổi vào ngày bay, không phải ngày đặt. Em bé ngồi lòng thường không chiếm ghế và chỉ được bay cùng người lớn. Chọn sai loại thì bước kiểm giá hoặc thất bại hoặc báo sai giá.
Giờ là giờ địa phương, và chặng không phải là leg
Giờ khởi hành và giờ đến được ghi theo giờ địa phương của từng sân bay. Đừng chuyển sang múi giờ của người dùng để hiển thị, và đừng tính thời lượng bằng phép trừ mà bỏ qua chênh lệch múi giờ. Một hành trình gồm các chặng; chặng có điểm dừng kỹ thuật gồm nhiều hơn một leg. Giao diện và dữ liệu của bạn phải thống nhất cái nào gọi là "điểm dừng".
Mọi chuyện vẫn xảy ra sau khi bán
Các hãng thay đổi lịch bay sau khi vé đã xuất. Một đặt chỗ đúng lúc xuất vé có thể vài tuần sau hiện giờ mới, số hiệu chuyến mới hoặc một chặng nối bị đứt, và tùy nhà cung cấp mà bạn biết qua thông báo, hàng đợi hoặc bằng cách truy xuất lại đặt chỗ. Hãy tính trước rằng đặt chỗ sẽ thay đổi sau khi bạn thôi để mắt tới nó.
Void không phải là hoàn tiền
Ngay sau khi xuất thường có một khoảng thời gian vé có thể được void như thể chưa từng tồn tại. Qua khoảng đó, chỉ còn hoàn vé theo điều kiện giá vé, có thể mất phí phạt hoặc không nhận lại gì. Khoảng thời gian và quy tắc thuộc về nhà cung cấp và thỏa thuận xuất vé; hãy đọc chúng trước khi làm nút "hủy".
Cái giá của sai sót
Lỗi trong tích hợp vé máy bay đắt theo một cách rất riêng: chúng rơi vào con người, không phải vào log. Một đặt chỗ trùng thành một cuộc gọi tới hãng và có thể là một thông báo ghi nợ vào tài khoản đại lý. Một khách đã bị trừ tiền mà không có vé thành hoàn tiền, khiếu nại và rủi ro chargeback. Một vé xuất ra mà thanh toán không thành công thành khoản nợ với hãng bay mà ai đó phải trả. Một thay đổi lịch bay không ai xử lý thành một hành khách đứng ở sân bay chờ chuyến bay đã cất cánh sớm hơn.
Không điều nào hiện ra trong kiểm thử luồng suôn sẻ. Hãy viết các luồng trục trặc trước: timeout lúc đặt chỗ, giá tăng, vé thất bại sau khi đã có PNR, void sau khi thanh toán thành công. Nếu những thứ đó được xử lý, luồng suôn sẻ là phần dễ.
Kiểm thử với API vé máy bay
Môi trường test của nhà cung cấp hữu ích nhưng không đầy đủ. Chúng thường yên ắng hơn production, nên hạng hết chỗ và đổi giá hiếm hơn, và một số hoàn toàn không mô phỏng timeout. Dùng chúng để nắm hình dạng lời gọi và lỗi kiểm tra dữ liệu, rồi lên kế hoạch chạy có kiểm soát trên production với đặt chỗ thật mà bạn void trong khoảng cho phép — và bộ phận vận hành biết bạn đang làm vậy.
Có nên tích hợp hay không là một câu hỏi riêng. Nếu thứ bạn thực sự cần là một cửa hàng chứ không phải kho dữ liệu thô trong hệ thống của mình, sự đánh đổi được trình bày trong white label hay tự xây booking engine, và lập luận tương tự áp dụng cho cổng B2B cho đại lý cấp 2. Nếu bạn thật sự muốn kho dữ liệu nằm trong code của mình, nền tảng này cung cấp API vé máy bay và khách sạn, và quyền truy cập bắt đầu bằng một cuộc trao đổi về nhu cầu của bạn chứ không phải một khóa tự phục vụ — đó cũng là lúc thích hợp để hỏi từng câu hỏi ở trên.