Backend API Design

API Versioning

Tất cả endpoints đều có prefix /api/v1/.

Authentication

Xem chi tiết tại Authentication Guide.

Các nhóm API

Auth

Method	Endpoint	Mô tả
POST	/api/v1/auth/login	Đăng nhập
POST	/api/v1/auth/logout	Đăng xuất
GET	/api/v1/auth/me	Thông tin user hiện tại

Teams

Method	Endpoint	Mô tả
GET	/api/v1/teams	Danh sách team của user
POST	/api/v1/teams	Tạo team mới
GET	/api/v1/teams/{team_id}	Chi tiết team
PATCH	/api/v1/teams/{team_id}	Cập nhật team
GET	/api/v1/teams/{team_id}/members	Danh sách thành viên
POST	/api/v1/teams/{team_id}/members	Thêm thành viên

Listings

Method	Endpoint	Mô tả
GET	/api/v1/teams/{team_id}/listings	Danh sách listing của team
POST	/api/v1/teams/{team_id}/listings	Tạo listing mới
POST	/api/v1/listings/preview	Preview listing trước khi tạo
GET	/api/v1/listings/{listing_id}	Chi tiết listing
PATCH	/api/v1/listings/{listing_id}	Cập nhật listing
DELETE	/api/v1/listings/{listing_id}	Xóa listing
POST	/api/v1/listings/{listing_id}/duplicate	Nhân bản listing
GET	/api/v1/listings/{listing_id}/children	Danh sách listing con
GET	/api/v1/listings/{listing_id}/parent	Listing cha

Listing Availability & Pricing

Method	Endpoint	Mô tả
GET	/api/v1/listings/{listing_id}/availability	Lịch khả dụng
PATCH	/api/v1/listings/{listing_id}/availability	Cập nhật availability
GET	/api/v1/listings/{listing_id}/pricing-rules	Quy tắc giá
POST	/api/v1/listings/{listing_id}/pricing/weekly	Giá theo tuần
PATCH	/api/v1/listings/{listing_id}/commission	Cập nhật hoa hồng
PATCH	/api/v1/listings/{listing_id}/policies	Cập nhật chính sách

Listing Calendar (iCal)

Method	Endpoint	Mô tả
GET	/api/v1/listings/{listing_id}/ical-urls	Danh sách iCal URL
POST	/api/v1/listings/{listing_id}/calendar/ical	Thêm iCal URL
POST	/api/v1/listings/{listing_id}/calendar/airbnb	Sync Airbnb calendar

Search

Method	Endpoint	Mô tả
GET	/api/v1/search	Tìm kiếm listing

Cart & Checkout

Method	Endpoint	Mô tả
GET	/api/v1/cart	Xem giỏ hàng
POST	/api/v1/cart	Thêm vào giỏ hàng
DELETE	/api/v1/cart/{item_id}	Xóa khỏi giỏ hàng
POST	/api/v1/checkout	Tiến hành checkout
POST	/api/v1/checkout/confirm	Xác nhận checkout

Bookings

Method	Endpoint	Mô tả
GET	/api/v1/bookings	Danh sách booking
GET	/api/v1/bookings/{booking_id}	Chi tiết booking
PATCH	/api/v1/bookings/{booking_id}	Cập nhật booking
POST	/api/v1/bookings/{booking_id}/cancel	Hủy booking

Payments

Method	Endpoint	Mô tả
POST	/api/v1/payments	Tạo payment
POST	/api/v1/payments/webhook	Payment webhook
GET	/api/v1/payments/{payment_id}	Chi tiết payment

Messaging

Method	Endpoint	Mô tả
GET	/api/v1/threads	Danh sách thread
POST	/api/v1/threads	Tạo thread
GET	/api/v1/threads/{thread_id}/channels	Danh sách channel
POST	/api/v1/threads/{thread_id}/channels/{channel_id}/messages	Gửi tin nhắn

Reviews

Method	Endpoint	Mô tả
GET	/api/v1/reviews	Danh sách đánh giá
POST	/api/v1/reviews	Tạo đánh giá

Financial

Method	Endpoint	Mô tả
GET	/api/v1/financial/transactions	Lịch sử giao dịch
GET	/api/v1/financial/summary	Tổng kết tài chính

Catalogs & Amenities

Method	Endpoint	Mô tả
GET	/api/v1/catalogs	Danh mục dữ liệu tham chiếu
GET	/api/v1/amenities	Danh sách tiện ích

Notifications

Method	Endpoint	Mô tả
GET	/api/v1/notifications	Danh sách thông báo
PATCH	/api/v1/notifications/{id}/read	Đánh dấu đã đọc

Locations

Method	Endpoint	Mô tả
GET	/api/v1/locations/provinces	Danh sách tỉnh/thành
GET	/api/v1/locations/countries	Danh sách quốc gia

Admin

Method	Endpoint	Mô tả
GET	/api/v1/admin/api-tokens	Quản lý API tokens
POST	/api/v1/admin/api-tokens	Tạo API token mới
DELETE	/api/v1/admin/api-tokens/{token_id}	Thu hồi token

Booking States

PENDING → CONFIRMED → CHECKED_IN → CHECKED_OUT → COMPLETED
    ↓           ↓
CANCELLED   CANCELLED

State	Mô tả
PENDING	Chờ xác nhận / chờ thanh toán
CONFIRMED	Đã xác nhận, chờ check-in
CHECKED_IN	Khách đã check-in
CHECKED_OUT	Khách đã check-out
COMPLETED	Hoàn tất
CANCELLED	Đã hủy

Listing States

State	Mô tả
DRAFT	Đang soạn thảo
ACTIVE	Đang hoạt động, có thể đặt
INACTIVE	Tạm ngưng
DELETED	Đã xóa (soft delete)