Booking Flow

Tổng quan

Cohost hỗ trợ ba hình thức đặt phòng:

Hình thức	Mô tả
Đặt theo đêm	Check-in/check-out theo ngày
Đặt trong ngày	Check-in và check-out trong cùng một ngày
Đặt theo giờ	Đặt theo số giờ tối thiểu

Luồng đặt phòng

1. Tìm kiếm

GET /api/v1/search?location=...&check_in=...&check_out=...&guests=...

Trả về danh sách listing khả dụng theo tiêu chí tìm kiếm. Hệ thống tự động clustering các listing gần nhau thành combo khi không đủ listing đơn lẻ.

2. Xem chi tiết listing

GET /api/v1/listings/{listing_id}
GET /api/v1/listings/{listing_id}/availability

Kiểm tra lịch khả dụng và giá theo ngày/giờ.

3. Thêm vào giỏ hàng

POST /api/v1/cart
{
  "listing_id": "uuid",
  "check_in": "2025-03-01T14:00:00",
  "check_out": "2025-03-03T12:00:00",
  "guests": 2
}

4. Checkout

POST /api/v1/checkout

Hệ thống thực hiện Soft-Lock — khóa tạm thời inventory trong Redis để tránh overbooking trong quá trình thanh toán. Lock có thời hạn (mặc định 15 phút).

5. Xác nhận & Thanh toán

POST /api/v1/checkout/confirm
{
  "payment_method": "...",
  "guest_info": { ... }
}

Nếu thanh toán thành công → booking được tạo và inventory bị khóa vĩnh viễn.

Nếu thanh toán thất bại → Soft-Lock được giải phóng, inventory trở lại khả dụng.

6. Sau khi booking

• Host và Guest nhận thông báo
• Thread chat được tạo tự động
• Lịch được đồng bộ với iCal (nếu có cấu hình)

All-or-Nothing Booking

Khi đặt nhiều listing cùng lúc (combo), hệ thống áp dụng logic All-or-Nothing:

• Tất cả listing phải khả dụng → booking thành công
• Bất kỳ listing nào không khả dụng → toàn bộ booking bị hủy, không charge phí

Parent-Child Booking

Khi đặt listing cha (nguyên căn):

• Tất cả listing con bị khóa tự động

Khi đặt listing con (phòng lẻ):

• Chỉ listing cha bị khóa (các phòng con khác vẫn có thể đặt)

Xem thêm: Listing Parent-Child

Hủy booking

POST /api/v1/bookings/{booking_id}/cancel

Chính sách hoàn tiền phụ thuộc vào refund_rule của listing:

• Hoàn tiền đầy đủ nếu hủy trước X ngày
• Không hoàn tiền nếu hủy muộn

Booking States

PENDING ──────────────────────────────────────────► CANCELLED
   │
   ▼ (thanh toán thành công)
CONFIRMED ────────────────────────────────────────► CANCELLED
   │
   ▼ (check-in)
CHECKED_IN
   │
   ▼ (check-out)
CHECKED_OUT
   │
   ▼ (xác nhận hoàn tất)
COMPLETED

Pricing

Giá được tính dựa trên:

Yếu tố	Mô tả
full_rate	Giá cơ bản theo đêm
prices_by_week	Giá theo từng ngày trong tuần
price_per_hour	Giá theo giờ
price_first_hours	Giá cho số giờ đầu tiên
price_rate_in_day	Hệ số giá đặt trong ngày (1x / 1.5x / 2x)
night_short_discount	Giảm giá đặt qua đêm muộn (0–70%)
last_minute_hour	Số giờ trước check-in để áp dụng last-minute discount
last_minute_discount	Giảm giá last-minute (%)
cleaning_fee	Phí dọn dẹp
extra_adult_rate	Phụ thu khách thêm
monthly_price	Giá thuê tháng (cố định)