Tài liệu REST API & Webhook

1. Tổng quan kiến trúc

Toàn bộ API dùng chung một Digital Core (cơ sở dữ liệu + logic nghiệp vụ). Có hai nhóm endpoint:

• API công khai (/api/v1/...): dùng cho chính website và có thể dùng trực tiếp từ App di động — không cần khoá riêng, dữ liệu vào thẳng Digital Core.
• Webhook tích hợp (/api/v1/integrations/<platform>/webhook): dành cho hệ thống bên ngoài (App, sàn TMĐT, mạng xã hội, đối tác) đẩy sự kiện vào Digital Core, xác thực bằng khoá API riêng theo từng đối tác.

Base URL: https://chatluong.vn (môi trường phát triển hiện tại: cổng cục bộ của máy chủ Flask).

2. Xác thực Webhook

Mỗi đối tác được cấp một API key riêng (lưu trong bảng partners), gửi kèm trong header của mọi request:

X-CLVN-API-KEY: clvn_demo_xxxxxxxxxxxxxxxxxxxxxxxx

Để xin cấp khoá API, liên hệ đội kỹ thuật CLVN qua trang Liên hệ, chọn nhu cầu "Tích hợp API/Webhook đối tác".

3. Danh sách nền tảng được hỗ trợ (platform)

4. Gửi sự kiện qua Webhook

POST /api/v1/integrations/{platform}/webhook
Content-Type: application/json
X-CLVN-API-KEY: {api_key_cua_ban}

{
  "event_type": "new_contact",
  "contact": {
    "name": "Nguyễn Văn A",
    "phone": "0900000000",
    "email": "a@congty.com",
    "company": "Công ty ABC"
  },
  "message": "Khách quan tâm gói Business OS"
}

Mọi payload gửi lên đều được ghi lại nguyên vẹn vào nhật ký tích hợp (integration_events), xem được trong Admin Console. Nếu payload có object contact.name, hệ thống tự động tạo một Lead mới để đội Sales theo dõi — mọi kênh đều đổ về cùng một phễu chăm sóc khách hàng.

Phản hồi thành công (HTTP 200):

{ "ok": true, "event_id": 42, "message": "Đã nhận sự kiện." }

Lỗi xác thực (HTTP 401):

{ "ok": false, "error": "Thiếu hoặc sai khoá API (X-CLVN-API-KEY)." }

Kiểm tra kết nối nhanh (không cần khoá API):

GET /api/v1/integrations/ping
→ { "ok": true, "service": "chatluong.vn integrations gateway", "status": "online" }

5. API công khai (dùng cho Website & App)

Các endpoint này không yêu cầu X-CLVN-API-KEY vì phục vụ trực tiếp website/App chính chủ — không dành cho tích hợp bên thứ ba (dùng nhóm Webhook ở trên cho trường hợp đó).

6. API quản trị (nội bộ)

Nhóm /api/v1/admin/... phục vụ Admin Console nội bộ, xác thực bằng Bearer Token lấy từ POST /api/v1/admin/login (hết hạn sau 12 giờ). Không cấp cho đối tác bên ngoài.

POST /api/v1/admin/login
{ "username": "admin", "password": "••••••••" }
→ { "ok": true, "token": "•••", "username": "admin" }

GET /api/v1/admin/summary
Authorization: Bearer {token}

7. Điểm nối AI thật (tham khảo kỹ thuật)

ChatBox AI Pro hiện chạy theo kịch bản quy tắc (rule-based) phía server, có một điểm nối duy nhất trong mã nguồn để thay bằng lệnh gọi mô hình AI thật khi công ty có khoá API — toàn bộ route và giao diện chat không cần thay đổi. Chi tiết được ghi chú trực tiếp trong mã nguồn backend (chatbot.py, hàm generate_reply).