Nhật ký hành trình công nghệ: Khi Stayntouch kết nối với Staklio tại Đà Nẵng

(Toàn bộ tình huống dưới đây là giả định, được viết nhằm mô tả quy trình tích hợp PMS với nền tảng quản lý bất động sản. Không dựa trên dự án thực tế nào.)

Tôi là kỹ sư PropTech người Việt, tham gia dự án tích hợp PMS cho một khu phức hợp nghỉ dưỡng hỗn hợp tại Đà Nẵng. Hệ thống PMS là Stayntouch; nền tảng quản lý chủ sở hữu và phân bổ doanh thu là Staklio. Câu chuyện bắt đầu từ ngày đầu tiên hai hệ thống kết nối.

Ngày đầu tiên kết nối API

Tôi ngồi trong phòng họp tạm ở tầng 12 tòa tháp A, mở Postman và gọi endpoint /bookings của Stayntouch. Phản hồi trả về JSON với các trường reservationId, unitCode, arrival, departure, totalRevenue, guestDetails. Staklio lúc này chỉ có schema rất cơ bản: externalId, unitId, checkIn, checkOut, grossAmount.

Mapping đầu tiên đơn giản: reservationId → externalId, unitCode → unitId. Tuy nhiên ngay lập tức xuất hiện vấn đề: Stayntouch gửi totalRevenue đã bao gồm VAT 10% và phí dịch vụ, còn Staklio cần tách riêng roomRevenue và nonRoomRevenue để tính tỷ lệ chia theo chủ sở hữu. Tôi phải viết một hàm chuyển đổi nhỏ chạy trong middleware, tách hai giá trị này theo quy tắc mà CFO khu resort đưa ra.

Tháng 1–3: Mapping dữ liệu đặt phòng và doanh thu

Stayntouch được cấu hình đẩy dữ liệu theo thời gian thực qua REST API mỗi khi booking được tạo hoặc chỉnh sửa. Webhook của Staklio lắng nghe sự kiện booking.created và booking.updated.

Trong 3 tháng đầu, chúng tôi gặp tình huống thú vị: một booking được chỉnh sửa 7 lần (thay đổi ngày, thêm giường phụ, hủy một đêm). Mỗi lần Stayntouch đẩy payload mới, Staklio phải quyết định ghi đè hay thêm phiên bản. Cuối cùng chọn cách lưu toàn bộ lịch sử và chỉ dùng bản ghi mới nhất để tính doanh thu chia sẻ.

Ví dụ đơn vị 2 phòng ngủ (mã đơn vị DN-A-1205) trong quý 2 có 12 booking. Tổng doanh thu gộp sau khi trừ VAT và phí dịch vụ là 312 triệu VND. Sau khi trừ 15% phí quản lý (46,8 triệu), còn 265,2 triệu. Tỷ lệ sở hữu: chủ A 60%, chủ B 40%. Staklio tự động ghi nhận:
– Chủ A: 159,12 triệu
– Chủ B: 106,08 triệu

Tất cả diễn ra trong vòng 4–6 giây sau khi Stayntouch xác nhận booking.

Tháng 4–8: Tự động hóa quyết toán và cổng chủ sở hữu

Giai đoạn này tập trung vào quyết toán hàng tháng. Stayntouch xuất file revenue_detail theo đơn vị, Staklio dùng API để kéo về và đối chiếu.

Vấn đề xuất hiện khi tỷ giá USD/VND thay đổi giữa ngày booking và ngày quyết toán, hoặc khi chính sách thuế Việt Nam điều chỉnh (ví dụ bổ sung phí môi trường 2%). Chúng tôi xây dựng hàng đợi ngoại lệ: nếu chênh lệch lớn hơn 3% so với dự kiến, bản ghi bị đẩy sang trạng thái “xem xét thủ công” kèm lý do. Cổng chủ sở hữu (dùng webhook) chỉ hiển thị số liệu đã được phê duyệt.

Tháng 9–18: Tối ưu hóa báo cáo đa chủ sở hữu

Đến giai đoạn này, số lượng đơn vị đã lên hơn 180. Vấn đề lớn nhất là báo cáo cho nhiều chủ sở hữu cùng lúc với nhiều tỷ lệ sở hữu khác nhau. Chúng tôi tái cấu trúc logic phân bổ doanh thu thành một dịch vụ riêng, sử dụng kiến trúc điều khiển sự kiện: Stayntouch → RabbitMQ → Staklio Revenue Engine.

Báo cáo đa chủ sở hữu giờ chạy dưới 12 giây cho 180 đơn vị thay vì 4–5 phút như trước. Đồng thời thêm cơ chế khóa idempotency để tránh trùng lặp khi webhook được thử lại.

Những gì thực sự xảy ra khi hai hệ thống kết nối

Stayntouch đẩy booking theo thời gian thực qua REST, Staklio lắng nghe webhook để cập nhật cổng chủ sở hữu ngay lập tức. Khi có chênh lệch (tỷ giá, thuế), bản ghi rơi vào hàng đợi ngoại lệ thay vì tự động đẩy số liệu sai cho chủ sở hữu. Tất cả đều có nhật ký kiểm toán chi tiết.

Nhận định ngắn

Rủi ro lớn nhất là dữ liệu tài chính của chủ sở hữu nằm ở hai hệ thống; cần mã hóa đầu cuối và giới hạn quyền truy cập theo vai trò. Về cơ hội, nếu Stayntouch có thể cung cấp thêm endpoint chuẩn, việc mở rộng sang các PMS khác tại Việt Nam sẽ dễ dàng hơn nhiều.