External / OTA API

Tổng quan

External API cho phép đối tác OTA (Booking.com, Agoda, Expedia, ...) và các hệ thống bên ngoài tích hợp với Cohost để:

• Đọc thông tin listing và availability
• Tạo và quản lý booking

Authentication

Dùng API Key qua header X-API-Key. Liên hệ team Cohost để được cấp key.

X-API-Key: cohost_api_xxxxxxxxxxxx

Scopes

Mỗi API key được gán một hoặc nhiều scopes:

Scope	Quyền
listings:read	Đọc thông tin listing và availability
bookings:read	Đọc thông tin booking
bookings:create	Tạo booking mới

Base URL

https://api.cohost.vn/api/v1/external

Interactive docs: GET /external-docs

API reference (generated from OpenAPI): xem thêm docs/api/external/* và guides/external-api.

---

Endpoints

Listings

Lấy danh sách listing

GET /api/v1/external/listings
X-API-Key: <key>

Query params:

Param	Type	Mô tả
page	int	Trang (default: 1)
limit	int	Số lượng (default: 20, max: 100)
team_id	string/int	Lọc theo team (type cụ thể xem OpenAPI External)

Response:

{
  "items": [
    {
      "id": "uuid",
      "name": "Villa Đà Lạt",
      "property_type": "villa",
      "listing_type": "ENTIRE_PLACE",
      "status": "ACTIVE",
      "location": {
        "city": "Đà Lạt",
        "province": "Lâm Đồng",
        "latitude": 11.9404,
        "longitude": 108.4583
      },
      "capacity": { "guests": 8, "bedrooms": 3, "beds": 4, "bathrooms": 2 },
      "pricing": {
        "full_rate": 2500000,
        "currency": "VND"
      }
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 20
}

Chi tiết listing

GET /api/v1/external/listings/{listing_id}
X-API-Key: <key>

Availability

GET /api/v1/external/listings/{listing_id}/availability?start_date=2025-03-01&end_date=2025-03-31
X-API-Key: <key>

Response:

{
  "listing_id": "uuid",
  "available_dates": ["2025-03-01", "2025-03-02", ...],
  "blocked_dates": ["2025-03-10", "2025-03-11"]
}

---

Bookings

Tạo booking

POST /api/v1/external/bookings
X-API-Key: <key>
Content-Type: application/json

{
  "listing_id": "uuid",
  "check_in": "2025-03-01T14:00:00",
  "check_out": "2025-03-05T12:00:00",
  "guests": 4,
  "guest_info": {
    "name": "Nguyen Van A",
    "phone": "+84901234567",
    "email": "guest@example.com"
  },
  "external_system": "BOOKING_COM",
  "external_booking_id": "BDC-123456"
}

Field	Bắt buộc	Mô tả
listing_id	✅	ID listing
check_in	✅	Thời gian check-in (ISO 8601)
check_out	✅	Thời gian check-out (ISO 8601)
guests	✅	Số khách
guest_info	✅	Thông tin khách
external_system	❌	Hệ thống nguồn (BOOKING_COM, AGODA, EXPEDIA, ...)
external_booking_id	❌	ID booking từ hệ thống nguồn

Lưu ý: Guest không cần tài khoản Cohost. Hệ thống tự động tạo guest user từ guest_info dựa trên email.

Danh sách booking

GET /api/v1/external/bookings
X-API-Key: <key>

Chi tiết booking

GET /api/v1/external/bookings/{booking_id}
X-API-Key: <key>

---

Quản lý API Key

API key được quản lý qua Admin API (yêu cầu JWT):

# Tạo API key mới
POST /api/v1/admin/api-tokens
Authorization: Bearer <jwt>

{
  "name": "Booking.com Integration",
  "team_ids": ["uuid-team-1"],
  "scopes": ["listings:read", "bookings:create", "bookings:read"],
  "rate_limit_per_minute": 60,
  "ip_whitelist": ["203.0.113.0/24"]
}

# Danh sách API keys
GET /api/v1/admin/api-tokens
Authorization: Bearer <jwt>

# Thu hồi API key
DELETE /api/v1/admin/api-tokens/{token_id}
Authorization: Bearer <jwt>

Lưu ý bảo mật:

• Token chỉ hiển thị một lần khi tạo — lưu lại ngay
• Token được hash SHA-256 khi lưu, không thể khôi phục
• Có thể giới hạn IP whitelist và rate limit per token

Rate Limiting

Loại	Giới hạn mặc định
External API	60 requests / phút / API key

Khi vượt giới hạn: HTTP 429 Too Many Requests

Error Codes

HTTP	Code	Mô tả
401	INVALID_API_KEY	API key không hợp lệ hoặc đã bị thu hồi
403	INSUFFICIENT_SCOPE	API key không có scope cần thiết
403	IP_NOT_WHITELISTED	IP không được phép
404	LISTING_NOT_FOUND	Listing không tồn tại
409	BOOKING_CONFLICT	Listing đã được đặt trong khoảng thời gian này
429	RATE_LIMIT_EXCEEDED	Vượt quá giới hạn request