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

Partner Integration - Quick Start

Hướng dẫn nhanh để bắt đầu tích hợp với Cohost External API.

Bước 1: Lấy API Key​

Liên hệ team Cohost để được cấp API Key. Bạn sẽ nhận được:

  • X-API-Key: API token cho authentication
  • team_ids: Danh sách team IDs mà API token có quyền truy cập

Bước 2: Kiểm tra kết nối​

Gọi endpoint health hoặc lấy danh sách listings:

curl "https://api.cohost.vn/api/v1/external/listings" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Response:

{
  "items": [],
  "total": 0,
  "page": 1,
  "limit": 20
}

Bước 3: Lấy danh sách Listings​

Lấy từ tất cả teams:

curl "https://api.cohost.vn/api/v1/external/listings?page=1&limit=20" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Filter theo teams cụ thể:

curl "https://api.cohost.vn/api/v1/external/listings?team_ids=[1,2,3]&page=1&limit=20" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Lưu ý: Format team_ids là JSON array string: "[1,2,3]". Nếu không có team_ids, API sẽ trả về listings từ tất cả teams mà token quản lý.

Bước 4: Kiểm tra Availability​

curl "https://api.cohost.vn/api/v1/external/listings/{listing_id}/availability?start_date=2025-03-01&end_date=2025-03-07" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Bước 5: Tạo Booking​

Lưu ý: team_id được tự động lấy từ listing_id. Listing phải thuộc một trong các teams mà token quản lý.

curl -X POST "https://api.cohost.vn/api/v1/external/bookings" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "listing_id": 123,
    "check_in_date": "2025-03-01",
    "check_out_date": "2025-03-05",
    "guest_number": 2,
    "guest_info": {
      "full_name": "Nguyen Van A",
      "phone": "+84901234567",
      "email": "guest@example.com"
    }
  }'

Lỗi có thể gặp:

  • 404: Listing không tồn tại
  • 403: Listing không thuộc teams mà token quản lý

Bước 6: Đăng ký và Login Customer (Tùy chọn)​

Nếu bạn cần quản lý customer có tài khoản để login (ví dụ: khách có thể đăng nhập vào portal của bạn), hãy sử dụng các endpoint customer management. Luồng cơ bản:

  1. Khách điền form đăng ký trên website của partner (email, full_name, phone, password).
  2. Backend của bạn gọi API POST /api/v1/external/customers/register đến Cohost với X-API-Key của partner.
  3. Cohost:
    • Validate API Key (status, expiration, IP whitelist, team_ids).
    • Tạo user trong Auth0 và trong database nội bộ Cohost.
    • Gửi email verify cho customer để kích hoạt tài khoản.
  4. Sau khi customer bấm link verify email, họ có thể đăng nhập:
    • Cách 1 (Khuyến nghị): Partner backend gọi POST /api/v1/external/customers/login với API Key
    • Cách 2: Customer login trực tiếp qua Auth0 Universal Login
  5. Sau khi login, customer nhận JWT token để gọi booking endpoints (xem phần Customer Members).

Register Customer​

curl -X POST "https://api.cohost.vn/api/v1/external/customers/register" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "full_name": "Nguyen Van A",
    "phone": "+84901234567",
    "password": "SecurePassword123"
  }'

Response:

{
  "user_id": 200,
  "email": "customer@example.com",
  "full_name": "Nguyen Van A",
  "teams": [1, 2],
  "message": "Customer registered successfully. Please verify email to activate account.",
  "requires_email_verification": true
}

List Customers​

Lấy từ tất cả teams:

curl "https://api.cohost.vn/api/v1/external/customers" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Filter theo team (nếu cần):

curl "https://api.cohost.vn/api/v1/external/customers?team_id=1" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Get Customer Detail​

curl "https://api.cohost.vn/api/v1/external/customers/200" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Update Customer​

curl -X PATCH "https://api.cohost.vn/api/v1/external/customers/200" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Nguyen Van B",
    "phone": "+84987654321"
  }'

Remove Customer from Team​

curl -X DELETE "https://api.cohost.vn/api/v1/external/customers/200/teams/1" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Customer Login​

curl -X POST "https://api.cohost.vn/api/v1/external/customers/login" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "SecurePassword123"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "user_id": 200,
  "email": "customer@example.com",
  "full_name": "Nguyen Van A",
  "teams": [1, 2, 3]
}

Check Login Status​

curl "https://api.cohost.vn/api/v1/external/customers/200/login-status" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Resend Verification Email​

curl -X POST "https://api.cohost.vn/api/v1/external/customers/200/resend-verification" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Lưu ý:

  • Customer sẽ được thêm vào tất cả các team mà API token có quyền
  • User sẽ nhận email để xác minh tài khoản trước khi login
  • Customer có thể là customer của nhiều team/partner
  • Auto-add on login: Khi customer login, nếu chưa có trong team_customers của các teams trong token, hệ thống sẽ tự động thêm vào
  • Auto-reactivate: Khi customer login, nếu membership bị INACTIVE, hệ thống sẽ tự động kích hoạt lại thành ACTIVE
  • Không cần register trước: Customer chỉ cần có tài khoản Auth0 là có thể login, không cần phải đăng ký qua POST /customers/register trước
  • Việc đăng nhập của customer sử dụng Auth0 (JWT), còn các call từ hệ thống partner sang Cohost External API vẫn dùng API Key (X-API-Key). Customer không gọi trực tiếp External API.
  • Sau khi login, customer nhận JWT access_token để gọi booking endpoints với header Authorization: Bearer <token>
  • QUAN TRỌNG: Customer phải verify email trước khi có thể tạo booking
  • Để customer xem và tạo booking sau khi đăng nhập, xem chi tiết trong Customer Members.

Interactive Docs​

Xem thêm tại:

  • Swagger UI: https://v2-staging.api.cohost.ai/external-docs
  • OpenAPI Schema: https://v2-staging.api.cohost.ai/external-openapi.json

Tiếp theo​