Chuyển đến nội dung
Blog

Xử lý lỗi API booking engine: ba sự cố gây tốn tiền

Ban biên tập Tekravel
Được viết với sự hỗ trợ của AI

Ticket hỗ trợ đến vào tối thứ Năm. Khách đã thanh toán, trang quay vòng rồi hiện một lỗi chung chung. Thẻ đã bị trừ tiền. Log của bạn cho thấy một lệnh POST tới nhà cung cấp mà không bao giờ nhận được phản hồi. Hãng bay có giữ chỗ không? Không ai trả lời được, và khách đang chờ. Xử lý lỗi API booking engine tốt phần lớn là công việc để không bao giờ rơi vào vị trí đó, hoặc ít nhất biết chính xác phải làm gì khi đã rơi vào.

Đa số tài liệu tích hợp coi lỗi là một danh mục mã trạng thái. Trong đặt chỗ, mã trạng thái là phần dễ. Thứ gây tốn tiền là một nhóm nhỏ tình huống mà request trông như thất bại nhưng thế giới thật vẫn thay đổi, hoặc trông như thành công nhưng thế giới thật không đổi. Ba tình huống dưới đây quan trọng hơn phần còn lại.

Sự cố thứ nhất: giá thay đổi giữa lúc tìm và lúc đặt

Kết quả tìm kiếm là một báo giá, không phải hợp đồng. Giá vé được cache, tồn kho được chia sẻ cho mọi kênh mà nhà cung cấp bán, và con số bạn hiển thị lúc 14:02 có thể đã cũ sau vài phút. Nhà cung cấp báo cho bạn ở bước create-booking, đôi khi bằng phản hồi rõ ràng "fare changed", đôi khi lặng lẽ trả về tổng tiền khác trong một phản hồi trông vẫn thành công.

Kiểu thứ hai mới nguy hiểm. Nếu mã của bạn đọc xác nhận, lưu booking và thu của khách đúng số họ đã thấy, phần chênh lệch sẽ trừ vào biên lợi nhuận của bạn, hoặc sau này vào một ADM. Vì vậy quy tắc đơn giản: so sánh tổng tiền nhà cung cấp xác nhận với tổng tiền khách đã chấp nhận, mỗi lần, trong code, trước khi bạn capture thanh toán.

Khi chúng khác nhau thì làm gì phụ thuộc vào độ lớn của chênh lệch và ai gánh. Vài xu làm tròn giữa các loại tiền là ngưỡng dung sai bạn đặt một lần. Bất cứ thứ gì lớn hơn quay lại khách dưới dạng giá mới kèm nút chấp nhận rõ ràng. Không bao giờ tự động hấp thụ, và không bao giờ tự động thu thêm.

Sự cố thứ hai: đã đặt nhưng chưa xuất vé

Có PNR không đồng nghĩa với có vé. Nhiều luồng tạo đặt chỗ trước rồi xuất e-ticket ở một bước riêng, với một giới hạn thời gian giữa hai bước. Nếu thanh toán thành công mà xuất vé thất bại, bạn đang giữ tiền của khách và một đặt chỗ sẽ tự hết hạn theo đồng hồ của nó.

Lỗi này hiếm khi ồn ào. Lệnh issue trả về lỗi hoặc timeout, và booking nằm ở trạng thái mà database của bạn gắn nhãn "paid" trong khi nhà cung cấp vẫn nói "held". Trong lúc đó hạn xuất vé đang chạy, và không như hàng đợi hỗ trợ của bạn, hãng bay không chờ.

Hãy xử lý nó như một trạng thái riêng, không phải biến thể của thành công hay thất bại. Một booking cần ít nhất các trạng thái sau: created, held, payment captured, issuing, ticketed, failed-and-refundable. "Payment captured, issuing" là trạng thái cần bộ đếm giờ: khi booking nằm đó quá lâu, một job nên đọc lại đặt chỗ từ nhà cung cấp và quyết định, thay vì chờ con người để ý. Quyết định này rẻ khi bạn biết hạn của nhà cung cấp, vì nó cho biết bạn được retry an toàn trong bao lâu trước khi phải hoàn tiền.

Sự cố thứ ba: timeout không rõ kết quả

Đây chính là ticket tối thứ Năm. Request của bạn đã đi, không có phản hồi nào quay lại, kết nối đứt hoặc gateway bỏ cuộc. Nhà cung cấp có thể đã xử lý đầy đủ, một phần, hoặc không hề.

Cám dỗ là retry. Đừng retry mù một lệnh create-booking, vì lần thứ hai có thể tạo đặt chỗ thứ hai, và bản trùng là chi phí thật: hai ghế bị giữ, có thể hai vé được xuất, và một cuộc cãi vã hoàn tiền ở một trong hai.

Thứ tự an toàn là: dừng, đọc, rồi quyết định. Dừng luồng phía khách bằng trạng thái trung thực "chúng tôi đang xác nhận booking của bạn". Đọc phía nhà cung cấp bằng cách tra booking theo mã tham chiếu bạn đã sinh trước khi gọi (đó là lý do bạn tạo mã tham chiếu client của riêng mình trước và gửi kèm nếu nhà cung cấp chấp nhận). Chỉ sau đó mới quyết định: tìm thấy nghĩa là tiếp tục từ trạng thái thật; không tìm thấy sau cửa sổ xử lý của chính nhà cung cấp nghĩa là retry một lần là an toàn.

Nếu nhà cung cấp không cho tra theo mã của bạn, hãy tìm theo tên hành khách, hành trình và ngày trong một khung hẹp, và coi một kết quả khớp là đã tìm thấy. Xấu xí, nhưng rẻ hơn nhiều so với một bản trùng.

Bảng quyết định để bạn phản biện

Bạn thấy gìBạn biết gìNên làm gìKhông nên làm gì
Nhà cung cấp trả "fare changed"Chưa có gì được đặtHiện tổng mới, xin chấp nhận, chạy lại createChạy lại với giá cũ và cầu may
Thành công nhưng tổng khác với số khách đã chấp nhậnBooking tồn tại ở giá mớiGiữ thanh toán, hỏi khách, void booking nếu khách từ chốiCapture số cũ và tự chịu phần chênh
Đã capture thanh toán, lệnh issue lỗiPNR tồn tại, trạng thái vé chưa rõĐọc lại đặt chỗ, retry issue trong hạn, hoàn tiền sau hạnĐánh dấu booking thất bại và quên PNR
Timeout khi createKết quả chưa rõTra theo mã của bạn, rồi tiếp tục hoặc retry một lầnRetry mù ngay lập tức
Timeout khi cancelBạn có thể vẫn chịu trách nhiệm với chặng bayĐọc lại trạng thái trước khi nói gì với kháchHiện "cancelled" vì nút đã được bấm

Có một dòng bạn có thể không đồng ý: một số đội hoàn tiền ngay ở lỗi xuất vé đầu tiên để trấn an khách. Với vé rẻ thì bào chữa được, với vé đắt thì là thói quen xấu, vì bạn có thể mất một mức giá mà một phút sau vẫn cứu được.

Làm sai thì tốn bao nhiêu

Mỗi sự cố có một hóa đơn khác nhau. Thay đổi giá bị bỏ sót là biên lợi nhuận mất trên mọi booking bị ảnh hưởng, thường không ai nhận ra cho đến khi đối soát. Booked-not-ticketed là khách đến sân bay với đặt chỗ đã hết hạn và một khoản trừ trên thẻ, tức là vừa chargeback vừa tổn hại uy tín. Retry mù khi timeout là đặt chỗ trùng, và hãng bay có kiểm tra đặt chỗ trùng; một chuỗi các ca như vậy là kiểu việc dẫn tới ADM.

Không điều nào trong số này xa lạ. Đó là phần đường ống tẻ nhạt phân biệt bản demo với thứ bạn có thể để chạy suốt cuối tuần.

Xây job đối soát trước khi bạn cần đến nó

Cả ba sự cố đều kết thúc giống nhau: database của bạn và của nhà cung cấp không khớp. Vì vậy hãy viết job so sánh chúng trước sự cố đầu tiên, không phải sau. Chạy hằng đêm là mức tối thiểu; vài phút một lần cho mọi thứ đang ở trạng thái chuyển tiếp thì tốt hơn. Job liệt kê các booking kẹt ở held, issuing hoặc unknown, hỏi nhà cung cấp, rồi sửa bản ghi hoặc mở ticket kèm bằng chứng.

Giữ mọi request và response của các lệnh đặt chỗ, kể cả timeout, cùng mã tham chiếu bạn đã gửi. Khi khách khiếu nại một khoản trừ tiền, log đó là lập luận của bạn. Nó cũng giữ cuộc bàn về độ trễ trung thực: xem những gì bạn có thể và không thể sửa về độ trễ API để hiểu vì sao timeout là một thực tế chứ không phải lỗi để diệt trừ.

Nếu bạn vẫn đang cân nhắc cách nối kết nối nhà cung cấp, hướng dẫn trong tích hợp API đặt vé máy bay bao quát thứ tự các lệnh gọi mà bài này giả định. Và nếu muốn trao đổi cách các trạng thái này ánh xạ sang API chuyến bay và khách sạn của chúng tôi, việc truy cập bắt đầu bằng một cuộc trò chuyện: xem trang API du lịch.

Ban biên tập Tekravel

Bộ phận công nghệ du lịch

Bộ phận công nghệ du lịch của Tekravel viết cho người trong ngành: chủ đại lý, đại lý gom vé và những lập trình viên tích hợp cho họ. Mỗi bài viết đều được đối chiếu với chính nền tảng mà nó mô tả trước khi đăng.