Kết nối Booking.com cho channel manager: loại phòng có số lượng, giá theo số khách và outbox để không mất cập nhật
Kết nối một phần mềm quản lý phòng với Booking.com nghe như "gọi API đẩy giá và phòng trống". Làm thật thì phần lớn lỗi không nằm ở việc gọi API, mà ở mô hình dữ liệu khác nhau giữa Booking.com và phần còn lại của thế giới (Airbnb, website riêng), cùng chuyện không được làm rơi một cập nhật nào.
Bài này chia sẻ những gì nhóm mình học được khi làm kết nối Booking.com cho một channel manager phục vụ homestay, villa: cách ghép phòng, cái bẫy "giá theo số khách" khiến kết nối hỏng mà không báo lỗi, và kiến trúc outbox để mỗi lần đổi giá đều tới được Booking.com.
Bài gốc viết cho chủ nhà (tiếng Việt): Channel manager Booking.com: kết nối thật sự hoạt động thế nào. Bài này là phiên bản kỹ thuật cho lập trình viên.
1. Luồng kết nối: không có mật khẩu nào cả
Channel manager không "đăng nhập hộ" vào Booking.com. Luồng đi như sau:
- Chủ chỗ nghỉ bật quyền trên extranet. Trong phần cài đặt kết nối của extranet Booking.com, chủ nhà chọn nhà cung cấp kết nối sẽ quản lý phòng trống và giá. Extranet có xác minh hai lớp, nên chỉ người giữ tài khoản làm được.
- Nhập Hotel ID. Mỗi chỗ nghỉ có một mã số, hiện ở đầu trang extranet. Phần mềm dùng mã này để biết chỗ nghỉ nào đã cấp quyền cho mình.
- Đọc cấu trúc phòng và gói giá, rồi cho người dùng ghép với phòng trong hệ thống của mình.
- Chạy thật: bắt đầu đẩy phòng trống, giá, quy tắc.
Điểm đáng học: quyền được cấp từ phía nền tảng, phần mềm không bao giờ cầm mật khẩu. Nếu bạn thiết kế tích hợp nào mà phải lưu mật khẩu người dùng của bên thứ ba, đó là dấu hiệu nên tìm cách khác.
2. Mô hình dữ liệu: loại phòng có số lượng
Đây là chỗ vấp nhiều nhất. Trên Airbnb, một tin đăng thường là một căn với một lịch. Trên Booking.com, chỗ nghỉ có các loại phòng, mỗi loại có số lượng phòng để bán.
Ví dụ một homestay 5 phòng ở Hội An: 3 phòng đôi hướng vườn giống hệt nhau và 2 phòng gia đình.
- Airbnb: 5 tin đăng, mỗi tin một lịch.
- Booking.com: 2 loại phòng, "Phòng Đôi Hướng Vườn" × 3 và "Phòng Gia Đình" × 2.

Cùng năm phòng, mô tả theo hai cách: tin đăng Airbnb và loại phòng Booking.com có số lượng.
Hệ thống phải hiểu cả hai cách tổ chức và luôn ra đúng 5 phòng thật, không bao giờ là 6. Vì vậy, với mỗi phòng ghép sang Booking.com, nhóm mình bắt người dùng xác nhận số lượng phòng trước khi chạy thật, và phòng trống đẩy đi luôn bị giới hạn bởi con số đó:
// Minh họa: phòng trống gửi đi = số phòng đã xác nhận trừ số đã bán, không âm,
// và không bao giờ lớn hơn số phòng đã xác nhận
const sellable = Math.max(0, confirmedUnits - bookedUnits);
Phòng chỉ có 1 đơn vị thì không bao giờ bị bán thành 2, dù dữ liệu ở đâu đó có sai.
Gợi ý ghép phòng: thà không gợi ý còn hơn gợi ý sai
Bản đầu tiên của màn ghép phòng dùng thuật toán đơn giản: tên trùng thì ghép, còn lại ghép theo thứ tự danh sách. Kết quả: "Suite" bị ghép với "Economy Single" chỉ vì đứng cùng vị trí.
Bản sau chấm điểm dựa trên ba tín hiệu:
- Lịch sử liên kết: phòng từng được ghép với loại phòng này trước đây (khi ngắt kết nối, hệ thống vẫn nhớ mã loại phòng cũ, nên ghép lại chỉ là "map lại").
- Tên: các từ chỉ loại phòng (double, family, suite…) được tính nặng hơn các từ chung chung.
- Sức chứa: ghép phòng 2 khách vào loại phòng tối đa 3 người sẽ tạo ra lỗi ở mục sau.
Và quy tắc quan trọng nhất ghi ngay đầu file:
// Suggestions RANK, they never force: a pair below the confidence threshold is simply not
// suggested (the row stays unticked), because a wrong default the host doesn't notice is
// worse than no default.
Một gợi ý sai mà người dùng không để ý còn tệ hơn không gợi ý gì.
3. Cái bẫy: giá theo số khách làm kết nối hỏng trong im lặng
Booking.com có thể tính giá theo số người ở (Occupancy-Based Pricing). Một dòng ghép giá thực chất là cặp (gói giá, số khách), và số khách đó phải thỏa cả hai phía:
- Phía Booking.com: không vượt
max_personscủa gói giá. Với gói tính theo số khách, phải là một trong các mức số khách mà gói đó khai báo. - Phía mình: phải là mức số khách mà gói giá của mình thật sự có giá.
Nếu không có mức nào thỏa cả hai, chuyện xảy ra rất khó chịu: API vẫn lưu dòng ghép, phòng hiện là "đã liên kết", nhưng giá không bao giờ được ghép. Mọi lần lưu giá sau đó đều không làm gì cả. Dấu vết duy nhất là một dòng log phía server, sau khi đã lưu xong.
Những lỗi mà Booking.com trả về khi đẩy sai số khách, nhóm mình đã gặp thật:
| Mã lỗi | Nguyên nhân |
|---|---|
OCCUPANCY_EXCEEDS_MAX_PERSONS |
Đẩy giá cho số khách lớn hơn max_persons của gói |
INVALID_USE_OF_SINGLE_OCCUPANCY |
Đẩy giá cho 1 khách vào gói không có giá 1 người |
Cách sửa: kiểm tra trước khi lưu, dùng chung một hàm
Nhóm mình viết một hàm thuần (pure function) matchOccupancy quyết định "gói giá này có ghép được không", và dùng chung cho cả hai nơi:
- Phía server, lúc đẩy dòng ghép thật.
- Phía client, trong màn ghép phòng, chạy lại mỗi lần người dùng đổi lựa chọn (
useMemo), trước khi lưu.
export type OccupancyMatch =
| { status: "ok"; levels: number[] }
| { status: "no-plan-levels" } // gói của mình không có mức giá nào
| { status: "obp-disjoint"; ourLevels: number[]; otaLevels: number[] } // hai bên không có mức chung
| { status: "exceeds-cap"; ourLevels: number[]; cap: number }; // vượt max_persons
Kiểu union có status giúp màn hình nói chính xác phòng nào, gói giá nào, hai bên lệch nhau ở mức số khách nào, trong lúc người dùng còn sửa được.
Hai nguyên tắc thiết kế:
- Cảnh báo và hành động dùng cùng một luật. Nếu client có logic kiểm tra riêng, sớm muộn gì nó cũng lệch với server, và màn hình sẽ hứa một điều mà lúc đẩy lại từ chối.
- File này không import gì của server (không Prisma, không
lib/server), chỉ dùng kiểu cấu trúc. Nhờ vậy nó vào được bundle của trình duyệt mà không kéo theo runtime của server.
4. Outbox: không làm rơi cập nhật nào
Giờ tới chuyện đẩy dữ liệu. Mỗi lần chủ nhà đổi giá hay chặn ngày, một lệnh ARI (Availability, Rates, Inventory) phải đi tới Booking.com. Hai rủi ro:
- Mất cập nhật. Lưu DB xong, server crash hoặc hàng đợi lỗi trước khi gửi đi. Trong DB giá đã đổi, trên Booking.com thì chưa, và không ai biết.
- Vượt giới hạn tốc độ. Sửa giá hàng loạt hay một loạt webhook đặt phòng cùng lúc tạo ra hàng trăm request. Nhà cung cấp kết nối giới hạn khoảng 20 lệnh ARI mỗi phút.
Nhóm mình giải quyết bằng transactional outbox:
Lưu giá ──▶ [ 1 transaction: cập nhật bảng giá + ghi 1 dòng vào ari_outbox ]
│
▼
relay đọc outbox, đẩy sang SQS FIFO
│
▼
drainer (1 luồng duy nhất) gửi đi, ≤ 20 lệnh/phút,
gặp 429 thì thử lại, quá số lần thì vào DLQ
Điểm mấu chốt: lệnh ARI được ghi vào bảng outbox trong cùng transaction với thay đổi giá. Hoặc cả hai cùng được lưu, hoặc không cái nào. Server có chết ngay sau commit thì dòng outbox vẫn còn đó, và relay sẽ gửi lại.
Thử lại theo backoff lũy thừa, có trần:
const MAX_ATTEMPTS = 10;
const BASE_BACKOFF_MS = 30_000;
const MAX_BACKOFF_MS = 6 * 60 * 60 * 1000; // 6 giờ
function backoffMs(attempts: number): number {
return Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempts);
}
Và khử trùng lặp bằng hash của nội dung lệnh. Bấm lưu hai lần thì chỉ có một dòng chờ gửi, còn lịch đã đổi thì hash khác và vẫn được xếp hàng:
export function ariDedupeKey(endpoint: AriEndpoint, propertyId: string, values: unknown[]): string {
return createHash("sha256").update(JSON.stringify([endpoint, propertyId, values])).digest("hex");
}
// insert với createMany({ skipDuplicates: true }) trên unique index của dedupe key
Vài chi tiết khác:
- SQS FIFO với group theo chỗ nghỉ, nên các lệnh của cùng một chỗ nghỉ đi đúng thứ tự, không lệnh nào vượt lệnh nào. Thứ tự quan trọng: "mở ngày 20" rồi "đóng ngày 20" mà đi ngược thì ngày đó bị mở sai.
- Drainer chạy một luồng duy nhất để kiểm soát tốc độ, thay vì trông vào việc bị trả 429 rồi mới lùi lại.
- Tương thích ngược: môi trường nào chưa có hàng đợi (ví dụ máy dev) thì gửi thẳng như cũ. Nhờ vậy có thể bật outbox cho từng môi trường một.
- Lỗi bị Booking.com từ chối được ghi lại để người dùng thấy, không bị nuốt trong im lặng.
5. Các luật an toàn khi đẩy dữ liệu
Ngoài kiến trúc, có vài luật nhỏ mà mỗi luật đều đến từ một sự cố thật:
- Không bao giờ đẩy giá bằng 0 hoặc giá tạm. Giá 0 đẩy lên một listing đang bán có thể làm trống cả lịch giá. Mọi chỗ gọi đều có điều kiện
> 0, tách riêng khỏi cờ "có đồng bộ giá hay không", để tắt bật tính năng không làm yếu luật an toàn. - Không đẩy gì trước khi người dùng xác nhận chạy thật. Kết nối xong thì hệ thống chỉ đọc: nhập đặt phòng tương lai về để người dùng đối chiếu. Đẩy ngay lúc kết nối có thể ghi đè giá đúng hoặc mở lại ngày đã đóng.
- Đổi ngày và hủy phòng phải về lại lịch. Khách Booking.com đổi và hủy khá nhiều, nhất là với đặt phòng hủy miễn phí. Mỗi lệnh hủy phải mở lại các đêm đó trên mọi kênh khác.
- Ngắt kết nối không bao giờ xóa chỗ nghỉ hay đặt phòng trên Booking.com. Nó chỉ dừng đồng bộ.

Sau khi chạy thật, mỗi phòng có một lịch cấp dữ liệu cho Booking.com và mọi kênh đã kết nối.
6. Những lỗi không phải do code
Kết nối đúng rồi vẫn còn vài nguồn lỗi nằm ở cách dùng. Đáng ghi vào tài liệu hướng dẫn hoặc hiện cảnh báo trong app:
- Số lượng phòng không khớp thực tế. Loại phòng ghi 4 trong khi chỉ có 3 thì Booking.com bán phòng thứ tư.
- Gói giá không được kết nối vẫn hiện giá cũ. Gói nào không dùng thì tắt trước khi kết nối.
- Đóng phòng thẳng trên extranet. Lịch của hệ thống không biết, lần cập nhật sau có thể mở lại. Mọi thao tác nên đi qua một lịch duy nhất.
- Hai phần mềm cùng kết nối một chỗ nghỉ thì đẩy hai con số khác nhau. Gỡ phần mềm cũ trước khi chạy thật phần mềm mới.
Và một giới hạn nên nói thẳng với người dùng: không cách đồng bộ nào đảm bảo hai khách không đặt cùng một đêm vào cùng một giây trên hai kênh. Việc làm được là khi chuyện hiếm đó xảy ra, cả hai đặt phòng nằm trên một lịch để thấy ngay và xử lý trước ngày khách đến.
7. Tóm lại
- Quyền kết nối được cấp từ phía nền tảng, không lưu mật khẩu của bên thứ ba.
- Mô hình loại phòng × số lượng khác hẳn mô hình một tin đăng một lịch. Bắt người dùng xác nhận số lượng, và giới hạn phòng trống theo con số đó.
- Gợi ý ghép chỉ để xếp hạng, không ép. Dưới ngưỡng tin cậy thì đừng gợi ý.
- Logic "ghép được hay không" là một hàm thuần dùng chung cho cảnh báo phía client và lệnh ghi phía server.
- Mọi lệnh ARI đi qua transactional outbox, hàng đợi FIFO theo chỗ nghỉ, drainer giới hạn tốc độ, backoff có trần và DLQ.
- Không đẩy giá 0, không đẩy trước khi chạy thật, ngắt kết nối không xóa gì.
Bài gốc (tiếng Việt, viết cho chủ nhà): Channel manager Booking.com: kết nối thật sự hoạt động thế nào. Các bài khác của nhóm ở blog Santara AI.
Bài viết được soạn với sự hỗ trợ của AI, từ bài gốc trên blog Santara AI và mã nguồn của nhóm.
All rights reserved