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

21. API Công Khai REST (External API — `X-API-Key`)

API REST dành cho tích hợp bên ngoài, xác thực bằng API key (không cần JWT). Mọi endpoint có tiền tố /api/public/. orgId được suy ra tự động từ API key.

Xác thực​

Gửi API key qua header:

X-API-Key: <api_key_cua_ban>

Lấy/khởi tạo API key tại Cài đặt → API & Webhook (hoặc POST /api/v1/settings/api-key/generate). Thiếu hoặc sai key → 401.

21.1 Liệt Kê Liên Hệ​

GET /api/public/contacts

Tham số truy vấn: search (tìm theo tên/SĐT/email), status, limit (mặc định 20, tối đa 100).

Phản hồi:

{
  "contacts": [
    {
      "id": "contact-123",
      "fullName": "Nguyễn Văn A",
      "phone": "0900000000",
      "email": "[email protected]",
      "source": "facebook",
      "status": "new",
      "notes": "Quan tâm gói Pro",
      "tags": ["vip"],
      "createdAt": "2026-06-01T03:00:00.000Z",
      "updatedAt": "2026-06-10T07:30:00.000Z"
    }
  ]
}

21.2 Lấy Chi Tiết Liên Hệ​

GET /api/public/contacts/:id

Trả về liên hệ kèm 5 lịch hẹn gần nhất và số lượng hội thoại. 404 nếu không tìm thấy.

21.3 Tạo Liên Hệ​

POST /api/public/contacts

Thân yêu cầu: (cần ít nhất fullName hoặc phone)

{
  "fullName": "Nguyễn Văn A",
  "phone": "0900000000",
  "email": "[email protected]",
  "source": "website",
  "status": "new",
  "notes": "Đăng ký từ landing",
  "tags": ["lead"]
}

Mã trạng thái: 201 (tạo thành công), 400 (thiếu fullName & phone).

21.4 Cập Nhật Liên Hệ​

PUT /api/public/contacts/:id

Thân yêu cầu giống 21.3 (các trường gửi lên sẽ được cập nhật). 404 nếu không tìm thấy.

21.5 Liệt Kê Hội Thoại​

GET /api/public/conversations

Tham số truy vấn: limit (mặc định 20, tối đa 100).

Phản hồi:

{
  "conversations": [
    {
      "id": "conv-123",
      "threadType": "user",
      "externalThreadId": "zalo-uid-xxx",
      "lastMessageAt": "2026-06-10T07:30:00.000Z",
      "unreadCount": 2,
      "isReplied": false,
      "contact": { "id": "contact-123", "fullName": "Nguyễn Văn A", "phone": "0900000000", "avatarUrl": null }
    }
  ]
}

21.6 Lấy Tin Nhắn Của Hội Thoại​

GET /api/public/conversations/:id/messages

Tham số truy vấn: limit (mặc định 50, tối đa 200). 404 nếu hội thoại không thuộc tổ chức.

Phản hồi:

{
  "messages": [
    {
      "id": "msg-1",
      "senderType": "contact",
      "senderName": "Nguyễn Văn A",
      "content": "Cho mình hỏi giá",
      "contentType": "text",
      "sentAt": "2026-06-10T07:29:00.000Z",
      "attachments": []
    }
  ]
}

21.7 Liệt Kê Lịch Hẹn​

GET /api/public/appointments

Tham số truy vấn: from, to (ISO date, lọc theo appointmentDate). Trả tối đa 100, kèm thông tin liên hệ.

21.8 Tạo Lịch Hẹn​

POST /api/public/appointments

Thân yêu cầu: (cần contactId và appointmentDate)

{
  "contactId": "contact-123",
  "appointmentDate": "2026-06-20",
  "appointmentTime": "14:30",
  "type": "call",
  "notes": "Gọi tư vấn gói Pro"
}

Mã trạng thái: 201, 400 (thiếu trường), 404 (liên hệ không tồn tại).

21.9 Gửi Tin Nhắn Zalo​

POST /api/public/messages/send

Gửi tin nhắn qua một nick Zalo đang kết nối của tổ chức.

Thân yêu cầu: (cần zaloAccountId, threadId, content)

{
  "zaloAccountId": "zalo-acc-123",
  "threadId": "zalo-uid-hoac-group-id",
  "content": "Xin chào, ZCRM đây!",
  "threadType": "user"
}
  • threadType: "user" (mặc định) hoặc "group".

Phản hồi: { "success": true }

Mã trạng thái: 200, 400 (thiếu trường), 404 (nick không tồn tại), 422 (nick chưa kết nối / không hoạt động trong pool).