goodgo-platform/docs/api-endpoints.md

Tham Khảo API Endpoint

Tất cả route được prefix với /api/v1/ ngoại trừ health check. Authentication dùng Bearer JWT token.

Tài liệu tương tác: Swagger UI có sẵn tại http://localhost:3001/api/v1/docs khi chạy API local.

Auth (/auth)

Method	Path	Auth	Mô tả
POST	/auth/register	Public	Đăng ký user mới
POST	/auth/login	Public	Đăng nhập bằng số điện thoại và mật khẩu
POST	/auth/refresh	Cookie	Làm mới access token bằng cookie refresh httpOnly
POST	/auth/logout	JWT	Đăng xuất và xóa cookie auth
POST	/auth/exchange-token	Public	Trao đổi cặp token OAuth lấy cookie httpOnly
GET	/auth/profile	JWT	Lấy hồ sơ user hiện tại
GET	/auth/profile/agent	JWT	Lấy hồ sơ agent của user hiện tại
PATCH	/auth/kyc	Admin	Verify trạng thái KYC của user

OAuth

Method	Path	Auth	Mô tả
GET	/auth/google	Public	Khởi tạo đăng nhập Google OAuth2
GET	/auth/google/callback	Public	Callback Google OAuth2
GET	/auth/zalo	Public	Khởi tạo đăng nhập Zalo OAuth2
GET	/auth/zalo/callback	Public	Callback Zalo OAuth2

Dữ Liệu User (GDPR)

Method	Path	Auth	Mô tả
DELETE	/users/me	JWT	Yêu cầu xóa tài khoản (thời hạn 30 ngày)
POST	/users/me/cancel-deletion	JWT	Hủy yêu cầu xóa tài khoản đang chờ
GET	/users/me/export	JWT	Export dữ liệu user (GDPR Điều 20)
DELETE	/users/:id/force	Admin	Force-delete user ngay lập tức

---

Listings (/listings)

Method	Path	Auth	Mô tả
POST	/listings	JWT + Quota	Tạo tin đăng bất động sản mới
GET	/listings	Public	Tìm kiếm và lọc tin đăng
GET	/listings/pending	Admin	Lấy tin đăng đang chờ duyệt
GET	/listings/:id	Public	Lấy chi tiết tin đăng theo ID
PATCH	/listings/:id/status	JWT	Cập nhật trạng thái tin đăng
POST	/listings/:id/media	JWT	Upload media (multipart file upload)
PATCH	/listings/:id/moderate	Admin	Duyệt một tin đăng

---

Search (/search)

Method	Path	Auth	Mô tả
GET	/search	Public	Tìm kiếm bất động sản full-text và faceted
GET	/search/geo	Public	Tìm kiếm theo bán kính địa lý
POST	/search/reindex	Admin	Reindex tất cả bất động sản trong Typesense

Saved Search (/saved-searches)

Method	Path	Auth	Mô tả
POST	/saved-searches	JWT	Lưu bộ lọc tìm kiếm
GET	/saved-searches	JWT	Liệt kê các tìm kiếm đã lưu
GET	/saved-searches/:id	JWT	Lấy chi tiết tìm kiếm đã lưu
PATCH	/saved-searches/:id	JWT	Cập nhật tìm kiếm đã lưu
DELETE	/saved-searches/:id	JWT	Xóa tìm kiếm đã lưu

---

Payments (/payments)

Method	Path	Auth	Mô tả
POST	/payments	JWT	Tạo thanh toán mới
GET	/payments	JWT	Liệt kê giao dịch của user đã xác thực
GET	/payments/:id	JWT	Lấy trạng thái thanh toán theo ID
POST	/payments/:id/refund	Admin	Hoàn tiền một thanh toán
POST	/payments/callback/:provider	Public	Webhook nhà cung cấp thanh toán (VNPay, MoMo, ZaloPay)

---

Subscriptions (/subscriptions)

Method	Path	Auth	Mô tả
GET	/subscriptions/plans	Public	Liệt kê tất cả plan subscription
GET	/subscriptions/plans/:tier	Public	Lấy plan subscription theo tier
POST	/subscriptions	JWT	Tạo subscription mới
PUT	/subscriptions/upgrade	JWT	Nâng cấp subscription hiện tại
DELETE	/subscriptions	JWT	Hủy subscription đang hoạt động
POST	/subscriptions/usage	JWT	Ghi nhận lượng sử dụng metered
GET	/subscriptions/quota/:metric	JWT	Kiểm tra quota còn lại theo metric
GET	/subscriptions/billing	JWT	Lấy lịch sử thanh toán

---

Admin (/admin)

Quản Lý User

Method	Path	Auth	Mô tả
GET	/admin/users	Admin	Liệt kê user với bộ lọc tùy chọn
GET	/admin/users/:id	Admin	Lấy chi tiết user theo ID
PATCH	/admin/users/status	Admin	Cập nhật trạng thái active của user
POST	/admin/users/ban	Admin	Ban hoặc unban user
POST	/admin/subscriptions/adjust	Admin	Điều chỉnh plan subscription của user
GET	/admin/dashboard	Admin	Lấy thống kê dashboard admin
GET	/admin/revenue	Admin	Lấy thống kê doanh thu theo khoảng ngày
GET	/admin/audit-logs	Admin	Lấy audit log admin

Moderation

Method	Path	Auth	Mô tả
GET	/admin/moderation	Admin	Lấy hàng đợi duyệt tin đăng
POST	/admin/moderation/approve	Admin	Duyệt một tin đăng
POST	/admin/moderation/reject	Admin	Từ chối một tin đăng
POST	/admin/moderation/bulk	Admin	Duyệt hoặc từ chối tin đăng hàng loạt
GET	/admin/kyc	Admin	Lấy hàng đợi xác minh KYC
POST	/admin/kyc/approve	Admin	Duyệt xác minh KYC
POST	/admin/kyc/reject	Admin	Từ chối xác minh KYC

---

Notifications (/notifications)

Method	Path	Auth	Mô tả
GET	/notifications/history	JWT	Lấy lịch sử thông báo
GET	/notifications/preferences	JWT	Lấy tùy chọn thông báo
PUT	/notifications/preferences	JWT	Cập nhật tùy chọn thông báo
GET	/notifications/unread	JWT	Lấy thông báo chưa đọc
PATCH	/notifications/:id/read	JWT	Đánh dấu thông báo đã đọc
PATCH	/notifications/read-all	JWT	Đánh dấu tất cả thông báo đã đọc
GET	/notifications/templates	JWT	Lấy các template thông báo có sẵn

---

Analytics (/analytics)

Tất cả endpoint analytics yêu cầu JWT và được giới hạn theo quota.

Method	Path	Auth	Mô tả
GET	/analytics/market-report	JWT + Quota	Lấy báo cáo thị trường cho một thành phố
GET	/analytics/price-trend	JWT + Quota	Lấy xu hướng giá cho một quận
GET	/analytics/heatmap	JWT + Quota	Lấy heatmap giá cho một thành phố
GET	/analytics/district-stats	JWT + Quota	Lấy thống kê theo quận
GET	/analytics/valuation	JWT + Quota	Lấy định giá bất động sản tự động (AVM)

---

Agents (/agents)

Method	Path	Auth	Mô tả
GET	/agents/me/dashboard	Agent	Lấy thống kê dashboard agent
POST	/agents/:agentId/recalculate-score	Admin	Tính lại điểm chất lượng agent

---

Inquiries (/inquiries)

Method	Path	Auth	Mô tả
POST	/inquiries	JWT	Tạo inquiry cho một tin đăng
GET	/inquiries/listing/:listingId	JWT	Liệt kê inquiry theo tin đăng
GET	/inquiries/agent/me	Agent	Liệt kê inquiry cho agent hiện tại
PATCH	/inquiries/:id/read	Agent	Đánh dấu inquiry đã đọc

---

Leads (/leads)

Method	Path	Auth	Mô tả
POST	/leads	Agent	Tạo lead
GET	/leads	Agent	Liệt kê lead cho agent
GET	/leads/stats	Agent	Lấy thống kê lead
PATCH	/leads/:id/status	Agent	Cập nhật trạng thái lead
DELETE	/leads/:id	Agent	Xóa lead

---

Reviews (/reviews)

Method	Path	Auth	Mô tả
POST	/reviews	JWT	Tạo một review
GET	/reviews	Public	Liệt kê review theo target
GET	/reviews/stats	Public	Lấy thống kê đánh giá tổng hợp cho một target
GET	/reviews/me	JWT	Lấy review của user đã xác thực
DELETE	/reviews/:id	JWT	Xóa review của chính mình

---

Health (/health)

Endpoint health không prefix với /api/v1/.

Method	Path	Auth	Mô tả
GET	/health	Public	Liveness probe
GET	/health/ready	Public	Readiness probe (DB + Redis)
GET	/health/db	Public	Kiểm tra kết nối database
GET	/health/redis	Public	Kiểm tra kết nối Redis

---

MCP (/mcp)

Method	Path	Auth	Mô tả
GET	/mcp/servers	JWT	Liệt kê các MCP server có sẵn
GET	/mcp/:serverName/sse	JWT	Mở kết nối SSE đến MCP server
POST	/mcp/:serverName/messages	JWT	Gửi message tới session MCP server

---

Metrics

Method	Path	Auth	Mô tả
POST	/web-vitals	Public	Ingest metric Core Web Vitals

---

Tóm Tắt Authentication

Loại Auth	Mô tả
Public	Không yêu cầu authentication
JWT	Yêu cầu header Authorization: Bearer <token>
Admin	JWT + role ADMIN
Agent	JWT + role AGENT
Quota	JWT + giới hạn quota subscription
Cookie	Dùng cookie refresh token httpOnly

Rate Limiting

Các endpoint sau có rate limit nghiêm ngặt hơn:

• Endpoint Auth (register, login, refresh): 10 req/60s
• OAuth callback: 10 req/60s
• Payment callback: 60 req/60s
• Endpoint MCP: 30 req/60s
• Mặc định: 60 req/60s