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

5. Liên Hệ & CRM

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

GET /api/v1/contacts

Liệt kê các liên hệ với bộ lọc nâng cao.

Tham Số Truy Vấn:

  • page - Số trang (mặc định: 1)
  • limit - Mục mỗi trang (mặc định: 50)
  • search - Tìm kiếm theo tên, điện thoại, email
  • source - Lọc theo nguồn: zalo, facebook, manual, v.v.
  • status - Lọc theo trạng thái (ví dụ: lead, customer, lost)
  • statusId - Lọc theo ID trạng thái tùy chỉnh
  • assignedUserId - Lọc theo người dùng được gán
  • threadType - Lọc theo loại cuộc trò chuyện: user, group
  • hasZalo - Lọc theo kết nối Zalo: true, false, unknown
  • scoreMin / scoreMax - Lọc theo phạm vi điểm số chứng chỉ
  • dateFrom / dateTo - Lọc theo phạm vi ngày hoạt động
  • sortBy - Trường sắp xếp: lastActivity, createdAt, leadScore
  • direction - asc hoặc desc

Phản hồi:

{
  "data": [
    {
      "id": "contact-001",
      "name": "Nguyễn Văn A",
      "email": "[email protected]",
      "phone": "+84.9.xxxx.xxxx",
      "source": "zalo",
      "status": "lead",
      "statusId": "status-001",
      "assignedUserId": "user-123",
      "avatar": "https://...",
      "leadScore": 85,
      "hasZalo": true,
      "friends": [
        {
          "zaloUid": "1234567890",
          "displayName": "Nguyễn Văn A",
          "accountId": "acc-001"
        }
      ],
      "notes": "Quan tâm đến gói premium",
      "tags": ["lead-nóng", "vip"],
      "lastActivity": "2026-06-05T16:45:00Z",
      "createdAt": "2026-03-10T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 500,
    "page": 1,
    "limit": 50,
    "pages": 10
  }
}

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

GET /api/v1/contacts/:id

Lấy đầy đủ thông tin liên hệ.

Phản hồi:

{
  "id": "contact-001",
  "name": "Nguyễn Văn A",
  "email": "[email protected]",
  "phone": "+84.9.xxxx.xxxx",
  "source": "zalo",
  "status": "lead",
  "statusId": "status-001",
  "assignedUserId": "user-123",
  "avatar": "https://...",
  "leadScore": 85,
  "hasZalo": true,
  "friends": [
    {
      "zaloUid": "1234567890",
      "displayName": "Nguyễn Văn A",
      "accountId": "acc-001"
    }
  ],
  "conversations": [
    {
      "id": "conv-001",
      "zaloAccountId": "acc-001",
      "messageCount": 45,
      "lastMessageAt": "2026-06-05T16:45:00Z"
    }
  ],
  "notes": [
    {
      "id": "note-001",
      "content": "Quan tâm đến gói premium",
      "createdBy": "user-123",
      "createdAt": "2026-06-01T10:00:00Z"
    }
  ],
  "tags": ["lead-nóng", "vip"],
  "appointments": [
    {
      "id": "apt-001",
      "title": "Cuộc Gọi Demo",
      "scheduledAt": "2026-06-10T14:00:00Z",
      "status": "scheduled"
    }
  ],
  "activities": [
    {
      "type": "message_received",
      "timestamp": "2026-06-05T16:45:00Z",
      "data": "Khách hàng gửi tin nhắn"
    }
  ],
  "createdAt": "2026-03-10T08:00:00Z",
  "updatedAt": "2026-06-05T17:35:00Z"
}

5.3 Tạo Liên Hệ​

POST /api/v1/contacts

Tạo liên hệ mới.

Thân Yêu Cầu:

{
  "name": "Trần Thị B",
  "email": "[email protected]",
  "phone": "+84.9.yyyy.yyyy",
  "source": "facebook",
  "status": "lead",
  "statusId": "status-001",
  "assignedUserId": "user-123",
  "notes": "Được giới thiệu bởi khách hàng hiện tại",
  "tags": ["giới-thiệu"]
}

Phản hồi: 201

{
  "id": "contact-002",
  "name": "Trần Thị B",
  "email": "[email protected]",
  "phone": "+84.9.yyyy.yyyy",
  "source": "facebook",
  "status": "lead",
  "createdAt": "2026-06-05T17:35:00Z"
}

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

PUT /api/v1/contacts/:id

Cập nhật thông tin liên hệ.

Thân Yêu Cầu:

{
  "name": "Trần Thị B",
  "email": "[email protected]",
  "status": "customer",
  "assignedUserId": "user-124",
  "tags": ["vip", "giới-thiệu"]
}

Phản hồi: 200

{
  "id": "contact-002",
  "name": "Trần Thị B",
  "email": "[email protected]",
  "status": "customer",
  "updatedAt": "2026-06-05T17:40:00Z"
}

5.5 Xóa Liên Hệ​

DELETE /api/v1/contacts/:id

Xóa liên hệ.

Phản hồi: 204 Không Có Nội Dung

5.6 Lấy Bạn Bè Liên Hệ​

GET /api/v1/contacts/:id/friends

Lấy kết nối bạn bè Zalo cho liên hệ.

Phản hồi:

[
  {
    "id": "friend-001",
    "zaloUid": "1234567890",
    "displayName": "Nguyễn Văn A",
    "accountId": "acc-001",
    "relationshipKind": "friend",
    "addedAt": "2026-03-10T08:00:00Z"
  }
]

5.7 Tạo Cuộc Hẹn​

POST /api/v1/appointments

Lên lịch hẹn với liên hệ.

Thân Yêu Cầu:

{
  "contactId": "contact-001",
  "title": "Demo Sản Phẩm",
  "description": "Giới thiệu các tính năng premium",
  "scheduledAt": "2026-06-10T14:00:00Z",
  "duration": 60,
  "type": "meeting",
  "location": "Cuộc Gọi Video",
  "assignedUserId": "user-123"
}

Phản hồi: 201

{
  "id": "apt-001",
  "contactId": "contact-001",
  "title": "Demo Sản Phẩm",
  "scheduledAt": "2026-06-10T14:00:00Z",
  "status": "scheduled",
  "createdAt": "2026-06-05T17:35:00Z"
}

5.8 Liệt Kê Cuộc Hẹn​

GET /api/v1/appointments

Liệt kê tất cả các cuộc hẹn.

Tham Số Truy Vấn:

  • page - Số trang
  • limit - Mục mỗi trang
  • status - Lọc: scheduled, completed, cancelled
  • contactId - Lọc theo liên hệ
  • dateFrom / dateTo - Phạm vi ngày

Phản hồi:

{
  "data": [
    {
      "id": "apt-001",
      "contactId": "contact-001",
      "contactName": "Nguyễn Văn A",
      "title": "Demo Sản Phẩm",
      "scheduledAt": "2026-06-10T14:00:00Z",
      "status": "scheduled",
      "createdAt": "2026-06-05T17:35:00Z"
    }
  ],
  "pagination": { "total": 25, "page": 1, "limit": 50 }
}

5.9 Thêm Ghi Chú cho Liên Hệ​

POST /api/v1/contacts/:id/notes

Thêm ghi chú/bình luận cho liên hệ.

Thân Yêu Cầu:

{
  "content": "Khách hàng quan tâm đến gói hàng năm. Theo dõi vào tuần tới."
}

Phản hồi: 201

{
  "id": "note-002",
  "contactId": "contact-001",
  "content": "Khách hàng quan tâm đến gói hàng năm...",
  "createdBy": "user-123",
  "createdAt": "2026-06-05T17:35:00Z"
}