iCal Sync

Tài liệu này mô tả cách Cohost đồng bộ lịch với các nền tảng bên ngoài thông qua iCal.

Scope: Áp dụng cho cả Internal Integration (dashboard Cohost) và bên thứ 3/OTA.

• Chủ nhà cấu hình iCal trong dashboard (Internal API).
• Đối tác có thể dùng iCal để đọc lịch Cohost hoặc cung cấp iCal cho Cohost thay vì gọi API custom.
  Xem thêm: Integration (Internal API), External API Guide.

---

1. Tổng quan

• Chủ nhà có thể cấu hình các URL iCal từ các nền tảng khác (ví dụ Airbnb, Google Calendar, OTA khác) để:
  • Import các ngày đã được đặt / blocked về Cohost.
  • Tránh overbooking khi cùng một listing được đăng trên nhiều kênh.
• Cohost cũng có thể expose iCal của chính mình để nền tảng khác đọc lịch Cohost.

---

2. Cấu hình iCal cho listing

Các endpoint chính (tham chiếu architecture/implementation-summary.md):

• POST /api/v1/listings/{id}/calendar/ical
  • Thêm / cập nhật iCal URL cho một listing.
• POST /api/v1/listings/{id}/calendar/airbnb
  • Endpoint tiện dụng dành riêng cho Airbnb (mapping nhanh thông tin cần thiết).

Các endpoint này thuộc Internal API, yêu cầu:

• JWT/Auth0 (Authorization: Bearer ...)
• X-Team-ID để xác định team context

Chi tiết hơn xem:

• guides/integration
• guides/listings (mục Availability & Calendar)

Sau khi cấu hình:

• Celery background tasks sẽ tự động:
  • Đồng bộ tất cả iCal URLs theo lịch (mặc định mỗi 15 phút).
  • Cập nhật listing_availability tương ứng với các event trong iCal.

---

3. Background tasks

Theo Implementation Summary, các task liên quan:

Task	Mô tả	Tần suất
sync_ical_calendars	Đồng bộ tất cả iCal URLs	Mỗi 15 phút
sync_airbnb_calendar	Đồng bộ lịch Airbnb	Mỗi 15 phút
sync_all_listings_calendars	Đồng bộ lịch cho tất cả listing	Mỗi 15 phút

Các task này:

• Parse file iCal (ICS).
• Chuyển event thành các khoảng blocked/available trong listing_availability.

---

4. Gợi ý tích hợp cho bên thứ 3

Để kết nối lịch với Cohost qua iCal:

• Pull từ Cohost:
  • Sử dụng iCal URL mà Cohost cung cấp (tuỳ cấu hình từng listing/team).
  • Hệ thống bên thứ 3 đọc ICS và cập nhật lịch riêng của mình.
• Push vào Cohost:
  • Cung cấp iCal URL public (read-only) cho Cohost.
  • Cohost định kỳ gọi URL đó để sync các event.

Ưu điểm:

• Tương thích với chuẩn iCal phổ biến.
• Không cần tích hợp API riêng cho từng nền tảng.

Nhược điểm:

• Độ trễ sync phụ thuộc vào tần suất job (ví dụ 15 phút).
• iCal thường chỉ mang thông tin ngày/giờ và trạng thái (busy/free), không mang theo đầy đủ metadata booking.

---

5. Liên quan tới Booking & Availability API

iCal sync là một nguồn dữ liệu bổ sung cho lịch:

• cùng với:
  • Booking được tạo trong Cohost.
  • Khóa lịch thủ công qua các API availability.
• Tất cả được hợp nhất trong listing_availability, và từ đó:
  • API search / availability / calendars trả về kết quả đã được hợp nhất.

Chi tiết thêm xem:

• guides/bookings
• architecture/booking-flow
• docs/03_PhanTich_BE.md (Calendar Service, Celery tasks, listing_availability)