Chuyển tới nội dung chính

Listing Management

Listing là gì?​

Listing là đơn vị cơ bản trong Cohost — đại diện cho một chỗ ở có thể đặt phòng. Mỗi listing thuộc về một Team và có thể là:

LoạiMô tả
INDEPENDENTListing độc lập, không liên kết cha/con
PARENTListing cha (nguyên căn), có thể chia thành nhiều phòng con
CHILDListing con (phòng lẻ), thuộc về một listing cha

Quy trình tạo listing​

Tạo listing theo 4 bước chính:

Bước 1 — Thông tin cơ bản​

  • Loại listing: INDEPENDENT / PARENT / CHILD
  • Loại bất động sản (property_type): house, villa, condo, resort, ...
  • Loại phòng (listing_type): ENTIRE_PLACE, PRIVATE_ROOM, SHARED_ROOM
  • View (view_types): beach, mountain, lake, city, ...
  • Số phòng: phòng ngủ, giường, phòng tắm, bếp, phòng khách
  • Diện tích (m²)
  • Tiện ích: chọn từ danh sách (xem Catalogs & Amenities)
  • Vị trí: địa chỉ, tọa độ GPS

Bước 2 — Mô tả chi tiết​

  • Tên listing (name) và tên nội bộ (nickname)
  • Mô tả (description)
  • Giới thiệu khu vực (neighborhood_overview)
  • Hình ảnh: tối thiểu 1 ảnh, khuyến nghị 5–10 ảnh

Bước 3 — Giá và chính sách​

Giờ check-in/out:

  • checkin_daily_hour / checkout_daily_hour

Giá cơ bản:

  • full_rate: giá theo đêm
  • prices_by_week: giá theo từng ngày trong tuần (7 ngày)
  • maximum_guest: số khách tối đa
  • extra_adult_rate / extra_child_rate: phụ thu khách thêm
  • cleaning_fee: phí dọn dẹp
  • security_deposit: tiền đặt cọc

Đặt trong ngày:

  • price_rate_in_day: hệ số giá (1x / 1.5x / 2x)

Đặt qua đêm muộn:

  • night_short_discount: giảm giá 0–70%

Đặt theo giờ:

  • allow_hourly_booking: bật/tắt
  • min_hours: số giờ tối thiểu (1–4)
  • price_first_hours / price_per_hour
  • Combo giờ (ví dụ: 3 giờ = 250k, 5 giờ = 350k)

Ưu đãi:

  • last_minute_rate: giảm giá last-minute 0–50%
  • monthly_price: giá thuê tháng

Hoa hồng:

  • Standard: 20% (commission_rate = 0.20)
  • Minimum: 15% (commission_rate = 0.15)

Dịch vụ bổ sung (extra_services):

  • Tên, mô tả, giá, đơn vị tính (per_night / per_hour / per_booking / per_person)

Bước 4 — Nội quy và chính sách​

Quy tắc chỗ ở:

  • outside_food_allowed, party_allowed, smoking_allowed
  • photography_allowed, pet_allowed, id_card_required
  • quiet_time_start / quiet_time_end
  • other_rules, refund_rule

Hình thức check-in:

LoạiMô tả
SELF_CHECKINTự check-in hoàn toàn
PARTIAL_SELF_CHECKINTự check-in một phần
HOST_CHECKINHost đón trực tiếp
RECEPTION_24HLễ tân 24/7
RECEPTION_LIMITEDLễ tân giờ hạn chế
  • door_code: mã cửa
  • wifi_name / wifi_password
  • checkin_guide_url: link hướng dẫn check-in

Instant booking & Calendar:

  • ical_urls: danh sách URL iCal để đồng bộ
  • airbnb_room_id: ID phòng Airbnb
  • website_url: website listing

API Endpoints​

Tạo listing​

POST /api/v1/listings
Authorization: Bearer <token>
X-Team-ID: <team_id>

Preview trước khi tạo​

POST /api/v1/listings/preview

Trả về validation errors/warnings mà không lưu dữ liệu.

Cập nhật listing​

PATCH /api/v1/listings/{listing_id}

Xóa listing​

DELETE /api/v1/listings/{listing_id}

Soft delete — listing chuyển sang state DELETED.

Nhân bản listing​

POST /api/v1/listings/{listing_id}/duplicate

Tạo bản sao với tên "{tên gốc} (Copy)", reset state về DRAFT.

Listing States​

StateMô tả
DRAFTĐang soạn thảo, chưa public
ACTIVEĐang hoạt động, có thể đặt
INACTIVETạm ngưng nhận booking
DELETEDĐã xóa (soft delete)

Validation​

Endpoint POST /api/v1/listings/preview trả về danh sách lỗi và cảnh báo theo từng bước mà không lưu dữ liệu — hữu ích để validate form trước khi submit.

{
  "errors": [
    { "step": 1, "field": "name", "message": "Tên listing là bắt buộc" }
  ],
  "warnings": [
    { "step": 2, "field": "images", "message": "Nên có ít nhất 5 ảnh" }
  ]
}

Draft Management​

Draft được lưu ở client-side (localStorage) trong quá trình tạo listing. Chỉ khi submit hoàn tất mới gọi API tạo listing.