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

Customer Members

Tài liệu này mô tả cách cho phép customer (khách hàng) có tài khoản để đăng nhập và xem booking của chính họ.

Tổng quan​

Khi partner cần:

  • Cho phép khách hàng đăng nhập vào portal của partner
  • Khách hàng có thể xem lịch sử đặt phòng của mình
  • Khách hàng nhận thông báo về booking

Partner có thể sử dụng tính năng Customer Member của Cohost.

Luồng hoạt động​

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Partner       │      │   Cohost API    │      │   Auth0         │
│   Website       │      │   (External)    │      │                 │
└────────┬────────┘      └────────┬────────┘      └────────┬────────┘
         │                        │                        │
         │ 1. Register customer  │                        │
         │──────────────────────>│                        │
         │                        │ 2. Create user        │
         │                        │──────────────────────>│
         │                        │                        │
         │                        │ 3. Send verify email  │
         │                        │<──────────────────────│
         │                        │                        │
         │ 4. Verify email link  │                        │
         │<───────────────────────│                        │
         │                        │                        │
         │ 5. Customer login     │                        │
         │──────────────────────>│                        │
         │                        │ 6. Auth0 login        │
         │                        │──────────────────────>│
         │                        │                        │
         │ 7. JWT Token          │                        │
         │<───────────────────────│                        │
         │                        │                        │
         │ 8. Get my bookings    │                        │
         │ (with JWT token)      │                        │
         │──────────────────────>│                        │

Bước 1: Đăng ký Customer (Partner → Cohost)​

Partner gọi API để đăng ký 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": {
    "email": "customer@example.com",
    "phone": "+84901234567",
    "full_name": "Nguyen Van A",
    "avatar_url": null,
    "date_of_birth": null,
    "gender": null,
    "language": "vi",
    "timezone": "Asia/Ho_Chi_Minh",
    "id": 200,
    "auth0_id": "auth0|xxxxxxxxxxxx",
    "is_verified": false,
    "verification_status": "PENDING",
    "rejection_reason": null,
    "status": "ACTIVE",
    "system_role": "USER",
    "host_status": "APPROVED",
    "host_application_at": null,
    "host_approved_at": null,
    "host_approved_by": null,
    "last_login_at": null,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z",
    "deleted_at": null,
    "teams": [],
    "email_verified": false
  },
  "customer_teams": [1, 2, 3]
}

Lưu ý:

  • Customer sẽ được thêm vào tất cả các team mà API token có quyền
  • Password được truyền đến Auth0 để tạo tài khoản
  • Email verification sẽ được gửi tự động

Bước 2: Customer xác minh email​

Customer nhận email từ Auth0 và bấm vào link xác minh. Sau khi verify, tài khoản được kích hoạt.

Bước 3: Customer đăng nhập​

Có 2 cách để customer đăng nhập:

Cách 1: Sử dụng External API Login Endpoint (Khuyến nghị)​

Partner backend gọi endpoint login trong External API:

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,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "user": {
    "email": "customer@example.com",
    "phone": "+84901234567",
    "full_name": "Nguyen Van A",
    "avatar_url": null,
    "date_of_birth": null,
    "gender": null,
    "language": "vi",
    "timezone": "Asia/Ho_Chi_Minh",
    "id": 200,
    "auth0_id": "auth0|xxxxxxxxxxxx",
    "is_verified": false,
    "verification_status": "PENDING",
    "rejection_reason": null,
    "status": "ACTIVE",
    "system_role": "USER",
    "host_status": "APPROVED",
    "host_application_at": null,
    "host_approved_at": null,
    "host_approved_by": null,
    "last_login_at": "2025-01-15T10:00:00Z",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z",
    "deleted_at": null,
    "teams": [],
    "email_verified": false
  },
  "customer_teams": [1, 2, 3]
}

Lưu ý:

  • Endpoint này yêu cầu API Key của partner (X-API-Key header)
  • Auto-add membership: Nếu customer chưa có trong team_customers của các teams trong token, hệ thống sẽ tự động thêm vào với status ACTIVE
  • Auto-reactivate: Nếu customer có membership nhưng status là 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
  • Trả về JWT access_token để customer dùng với booking endpoints

Cách 2: Sử dụng Auth0 Universal Login hoặc SDK​

Partner có thể redirect customer đến trang login của Auth0 hoặc sử dụng Auth0 SDK:

Auth0 Universal Login:

https://{your-domain}/authorize?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=openid%20profile%20email&
  audience={api_audience}

Hoặc gọi Auth0 API trực tiếp:

curl -X POST "https://cohost.auth0.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "username": "customer@example.com",
    "password": "customer_password",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "audience": "https://api.cohost.vn",
    "scope": "openid profile email"
  }'

Quan trọng: Partner backend cần lưu trữ access_token để sử dụng cho các API calls tiếp theo.

Bước 4: Customer xem và tạo booking​

Sau khi có JWT token, customer có thể gọi các booking API. QUAN TRỌNG: Customer phải verify email trước khi có thể tạo booking.

Kiểm tra verification status​

Partner có thể kiểm tra xem customer đã verify email chưa (từ Auth0):

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

Response:

{
  "user_id": 200,
  "email": "customer@example.com",
  "email_verified": true,
  "has_auth0_account": true
}

Lưu ý: Trạng thái email_verified được lấy trực tiếp từ Auth0, đảm bảo luôn cập nhật và chính xác.

Preview Booking (Tính toán giá)​

curl -X POST "https://api.cohost.vn/api/v1/checkout/preview" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "listing_id": 123,
        "check_in_date": "2025-03-01",
        "check_out_date": "2025-03-05",
        "check_in_time": "14:00:00",
        "check_out_time": "11:00:00",
        "guest_number": 2
      }
    ],
    "currency": "VND"
  }'

Tạo Booking​

Lưu ý: Customer phải verify email trước khi có thể tạo booking. Nếu chưa verify, sẽ nhận error USER_NOT_VERIFIED.

curl -X POST "https://api.cohost.vn/api/v1/checkout/confirm" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "listing_id": 123,
        "check_in_date": "2025-03-01",
        "check_out_date": "2025-03-05",
        "check_in_time": "14:00:00",
        "check_out_time": "11:00:00",
        "guest_number": 2
      }
    ],
    "payment_method": "BANK_TRANSFER",
    "currency": "VND"
  }'

Error nếu chưa verify email:

{
  "error": "USER_NOT_VERIFIED",
  "message": "User email is not verified. Please verify your email before creating a booking.",
  "details": {
    "user_id": 200,
    "verification_status": "PENDING",
    "action_required": "VERIFY_EMAIL"
  }
}

Xem danh sách booking​

curl "https://api.cohost.vn/api/v1/bookings/my" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response:

[
  {
    "id": 123,
    "listing_id": "uuid-listing",
    "listing_name": "Homestay Da Nang",
    "check_in": "2025-03-01",
    "check_out": "2025-03-05",
    "guests": 2,
    "total_price": 5000000,
    "state": "CONFIRMED",
    "payment_status": "PAID",
    "created_at": "2025-02-15T10:00:00Z"
  }
]

Các endpoints cho Customer​

EndpointMethodDescriptionAuth
/api/v1/checkout/previewPOSTPreview booking priceJWT Bearer
/api/v1/checkout/confirmPOSTCreate booking (requires verified email)JWT Bearer
/api/v1/bookings/myGETDanh sách booking của customerJWT Bearer
/api/v1/bookings/{booking_id}GETChi tiết một bookingJWT Bearer
/api/v1/auth/meGETThông tin profile của customerJWT Bearer
/api/v1/auth/mePATCHCập nhật profile của customerJWT Bearer
/api/v1/auth/logoutPOSTĐăng xuấtJWT Bearer

Customer xem chi tiết booking​

curl "https://api.cohost.vn/api/v1/bookings/123" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response:

{
  "id": 123,
  "listing_id": "uuid-listing",
  "listing_name": "Homestay Da Nang",
  "listing_address": "123 ABC Street, Da Nang",
  "check_in": "2025-03-01",
  "check_out": "2025-03-05",
  "guests": 2,
  "guest_info": {
    "name": "Nguyen Van A",
    "phone": "+84901234567",
    "email": "customer@example.com"
  },
  "total_price": 5000000,
  "state": "CONFIRMED",
  "payment_status": "PAID",
  "created_at": "2025-02-15T10:00:00Z",
  "host_info": {
    "name": "Host Name",
    "phone": "+84987654321"
  }
}

Customer cập nhật profile​

curl -X PATCH "https://api.cohost.vn/api/v1/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Nguyen Van B",
    "phone": "+84911111111"
  }'

API Key Requirements​

Lưu ý: Scope checking đã được bỏ. Chỉ cần API Key hợp lệ là đủ để sử dụng tất cả các tính năng customer member.

Lưu ý bảo mật​

  1. JWT Token: Token nhận từ Auth0 có hiệu lực trong 24 giờ (86400 giây). Partner cần handle token expiration và refresh token khi cần.

  2. Password Policy: Auth0 yêu cầu password ít nhất 8 ký tự, có chữ hoa, chữ thường và số.

  3. Email Verification:

    • Customer phải verify email trước khi có thể login. Nếu chưa verify, Auth0 sẽ block login attempt.
    • QUAN TRỌNG: Customer phải verify email trước khi có thể tạo booking. Nếu chưa verify, endpoint POST /api/v1/checkout/confirm sẽ trả về error USER_NOT_VERIFIED.
    • Partner có thể kiểm tra verification status qua GET /api/v1/external/customers/{user_id}/email-verification (lấy từ Auth0).

  4. Rate Limiting: Auth0 có giới hạn request. Partner nên implement caching và handle 429 errors.

Xem thêm​