Bookings
Tài liệu này mô tả cách tích hợp luồng đặt phòng với Cohost.
1. Tổng quan
Cohost hỗ trợ các hình thức đặt phòng:
- Overnight: Đặt qua đêm
- Day-use: Đặt trong ngày
- Hourly: Đặt theo giờ
Luồng booking cơ bản:
- Chọn listing
- Chọn ngày/giờ check-in/check-out
- Nhập thông tin khách
- Preview giá
- Confirm booking
2. Calendar & Time Slots
2.1. Lấy available time slots
API lấy danh sách các slot (theo giờ) có thể đặt:
GET /api/v1/listing-availability/listings/{listing_id}/calendars/unavailable
Query Parameters:
| Parameter | Kiểu | Mô tả |
|---|---|---|
start_time | string | Thời gian bắt đầu (YYYY-MM-DDTHHmm) |
end_time | string | Thời gian kết thúc (YYYY-MM-DDTHHmm) |
Response:
[
"2026-01-02T1400",
"2026-01-02T1500",
"2026-01-02T1600"
]
Đặc điểm:
- Format:
YYYY-MM-DDTHHmm(không có dấu hai chấm) - Trả về các slot không thể đặt (BOOKED, BLOCKED, SOFT_LOCK chưa hết hạn)
- FE sẽ tạo lưới hourly grid và đánh dấu các slot trong response là unavailable
2.2. Lấy calendar theo tháng
GET /api/v1/listing-availability/listings/{listing_id}/calendar?year=2026&month=1
Response:
[
{
"id": 1,
"listing_id": 1,
"date": "2026-01-01",
"start_at": "2026-01-01T14:00:00",
"end_at": "2026-01-02T12:00:00",
"state": "BOOKED",
"note": null
}
]
3. Preview Booking
Xem trước giá trước khi confirm:
POST /api/v1/checkout/preview
3.1 Request
{
"items": [
{
"listing_id": 1,
"check_in_date": "2026-03-01",
"check_out_date": "2026-03-03",
"check_in_time": "14:00:00",
"check_out_time": "12:00:00",
"guest_number": 2,
"adult_number": 2,
"children_number": 0,
"rooms": 1,
"combo_id": 5,
"extra_service_ids": [1, 3]
}
],
"currency": "VND"
}
Các trường:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
listing_id | int | ✓ | ID của listing |
check_in_date | date | ✓ | Ngày nhận phòng |
check_out_date | date | ✓ | Ngày trả phòng |
check_in_time | time | Giờ nhận phòng | |
check_out_time | time | Giờ trả phòng | |
guest_number | int | ✓ | Tổng số khách |
adult_number | int | Số khách người lớn (để tính phí riêng) | |
children_number | int | Số trẻ em (để tính phí riêng) | |
rooms | int | Số phòng | |
combo_id | int | ID combo muốn áp dụng | |
extra_service_ids | array | Danh sách dịch vụ thêm |
Ghi chú:
- Discounts (last-minute, monthly) được điều khiển bởi Listing configuration, không phải request params
- Nếu có
adult_numbervàchildren_number, hệ thống sẽ tính phí riêng cho người lớn và trẻ em
3.2 Response
{
"items": [
{
"listing_id": 1,
"listing_name": "Villa Đà Lạt",
"check_in_date": "2026-03-01",
"check_out_date": "2026-03-03",
"nights": 2,
"guest_number": 2,
"adult_number": 2,
"children_number": 0,
"pricing_type": "nightly",
"base_price": 5000000,
"combo_price": 0,
"hourly_price": 0,
"daily_price": 2500000,
"night_short_discount": 0,
"last_minute_discount": 0,
"monthly_discount": 0,
"total_discount": 0,
"extra_guest_fee": 0,
"extra_adult_fee": 0,
"extra_child_fee": 0,
"cleaning_fee": 100000,
"extra_services_total": 50000,
"extra_services": [
{
"id": 1,
"name": "Ăn sáng",
"price": 50000,
"price_unit": "per_person",
"quantity": 1
}
],
"earning": 5150000,
"deposit": 500000,
"currency": "VND"
}
],
"total_nights": 2,
"total_earning": 5150000,
"total_discount": 0,
"total_extra_guest_fee": 0,
"total_cleaning_fee": 100000,
"total_extra_services": 50000,
"total_deposit": 500000,
"currency": "VND",
"estimated_total": 5650000
}
Các trường trong Response:
| Trường | Mô tả |
|---|---|
pricing_type | Loại giá: combo, nightly, hourly, daily, night_short |
base_price | Giá gốc trước discount |
combo_price, hourly_price, daily_price | Giá theo từng loại booking |
night_short_discount | Giảm giá night short |
last_minute_discount | Giảm giá last-minute |
monthly_discount | Giảm giá theo tháng |
extra_adult_fee | Phí khách người lớn tăng thêm |
extra_child_fee | Phí trẻ em tăng thêm |
extra_services | Chi tiết từng dịch vụ thêm |
3.3 Discount Configuration (Listing)
Discounts được cấu hình trong Listing:
| Field | Mô tả |
|---|---|
last_minute_hour | Số giờ trước check-in để áp dụng discount |
last_minute_discount | % giảm giá last-minute |
monthly_price | Giá cố định theo tháng (nếu > 0, áp dụng cho stay >= 30 nights) |
4. Confirm Booking
Tạo booking và thanh toán:
POST /api/v1/checkout/confirm
Request:
{
"items": [
{
"listing_id": 1,
"check_in_date": "2026-03-01",
"check_out_date": "2026-03-03",
"check_in_time": "14:00:00",
"check_out_time": "12:00:00",
"guest_number": 2,
"adult_number": 2,
"children_number": 0,
"rooms": 1,
"combo_id": 5,
"extra_service_ids": [1, 3]
}
],
"currency": "VND",
"payment_method": "VNPAY"
}
Response:
{
"master_reservation_id": 100,
"reservations": [
{
"id": 101,
"listing_id": 1,
"status": "CONFIRMED"
}
],
"payment_status": "PENDING",
"payment_url": "https://payment-gateway.com/pay/xxx"
}
Ghi chú:
- Request cho
/checkout/confirmhỗ trợ các trường tương tự như/checkout/preview - Các trường
combo_idvàextra_service_idscho phép chọn combo và dịch vụ thêm khi đặt phòng
5. External Booking (Partner/OTA)
5.1. Tạo booking từ bên ngoài
POST /api/v1/external/bookings
Auth: X-API-Key
Request:
{
"listing_id": 1,
"guest_info": {
"full_name": "Nguyen Van A",
"email": "guest@example.com",
"phone": "+84901234567"
},
"check_in_date": "2026-03-01",
"check_out_date": "2026-03-03",
"guest_number": 2,
"nights": 2,
"payment_method": "CASH",
"external_system": "AIRBNB",
"external_booking_id": "ABC123"
}
Response:
{
"id": 200,
"status": "CONFIRMED"
}
5.2. Lấy danh sách bookings
GET /api/v1/external/bookings
Query Parameters:
| Parameter | Kiểu | Mô tả |
|---|---|---|
listing_id | int? | Lọc theo listing |
page | int? | Số trang |
limit | int? | Số items/trang |
6. Booking States
Trạng thái booking:
| State | Mô tả |
|---|---|
PENDING | Chờ xác nhận |
CONFIRMED | Đã xác nhận |
CHECKED_IN | Đã nhận phòng |
CHECKED_OUT | Đã trả phòng |
COMPLETED | Hoàn thành |
CANCELLED | Đã hủy |
7. Cancel Booking
Hủy booking:
POST /api/v1/bookings/{booking_id}/cancel
Áp dụng chính sách hoàn tiền (refund_rule) của listing.