Khách hàng

Các API liên quan đến người dùng, khách hàng

Trên hệ thống CareSoft. Mỗi người dùng/Khách hàng được định nghĩa bằng số điện thoại hoặc email. Một người dùng có tối đa ba (03) số điện thoại và hai (02) email làm định danh.

Các trường thông tin của người dùng

STT

Tên trường

Kiểu dữ liệu

Ghi chú

INT

ID của người dùng

username

TEXT(255)

Họ tên

Email người dùng

email2

Email thứ 2

phone_no

TELEPHONE

Số điện thoại của người dùng

phone_no2

TELEPHONE

Số điện thoại thứ 2

phone_no3

TELEPHONE

Số điện thoại thứ 3

created_at

DATETIME

Ngày tạo

updated_at

DATETIME

Ngày cập nhật.

created_from

INT

Nguồn tạo (Xem danh sách nguồn) Cột Source ID

organization_id

INT

ID tổ chức

organization

TEXT(255)

Tên tổ chức

city_id

INT

ID thành phố (Tham khảo danh sách tỉnh thành)

district_id

INT

ID huyện/quận

address

TEXT(255)

Địa chỉ

gender

INT

Giới tính: 0. Nam, 1 Nữ, 2 Không xác định

facebook

INT

ID facebook (De-precade)

campaign_handler_id

INT

ID chiến dịch xử lý

custom_fields

ARRAY

Danh sách trường động

follower_id

INT

Id của chuyên viên quản lý (xem Chuyên viên Trường ID

take_phone_at

DATETIME

Thời điểm thu thập được số điện thoại (Null hoặc Ngày tháng)

take_email_at

DATETIME

Thời điểm thu thập được email(Null hoặc Ngày tháng)

Thêm mới khách hàng

Để thêm mới khách hàng. Lập trình viên cần tạo 1 đối tượng contact kiểu Json Object có cấu trúc sau. Các trường dữ liệu

Mẫu body request tạo khách hàng

{
    "contact": {
        "email": "{{Email khách hàng}}",
        "phone_no": "{{Số điện thoại khách hàng}}",
        "username": "{{Họ tên của khách hàng",
        "address":"{{Địa chỉ khách hàng}}",
        "gender":"{{Giới tính của khách hàng}}"
        "custom_fields": [
            {
                "id": {{ID trường động khách hàng}},
                "value": "{{Giá trị trường động}}"
            }
        ]
    }
}

Ví dụ tham khảo mẫu POSTMAN tạo mới khách hàng

Thêm mới khách hàng

POST {{domain}/api/v1/contacts

Headers

Name

Type

Description

String

Thông tin xác thực chung

Request Body

Name

Type

Description

contact

Object

Cấu trúc object ở trên

{
    "code": "ok",
    "contact": {
        "phone_no": "024***22",
        "updated_at": "2023-04-12 14:54:24",
        "created_at": "2023-04-12 14:54:24",
        "id": 63216006,
        "email": "uyel**@**l.com",
        "username": "Le ***yen"
    }
}

STT

Tên trường

Kiểu

Ý nghĩa

code

String

"ok": Thành công, "errors": Thất bại

contact

Object

Đối tượng thông tin khách hàng được tạo mới

contact.id

Int

ID khách hàng (?)

contact.phone_no

String

Số điện thoại

contact.email

contact.username

String

Họ tên khách hàng

contact.created_at

Ngày tạo

contact.updated_at

Ngày cập nhật

Thông tin trùng lặp hoặc thiếu sẽ thể hiện qua thông báo lỗi này

{
    "code": "errors",
    "message": "email already exist",
    "extra_data": {
        "duplicate_id": "63216006"
    }
}

{
    "code": "errors",
    "message": "phone_no already exist",
    "extra_data": {
        "duplicate_id": "63216007"
    }
}

Cập nhật khách hàng

Trong trường hợp có thay đổi thông tin khách hàng, VD: Thay đổi số điện thoại, email hay thông tin người phụ trách hoặc các thông tin phân loại được tùy biến. Lập trình viên sử dụng hàm này để cập nhật dữ liệu lên hệ thống

Gợi ý: Trong một số trường hợp không lưu contactId của khách hoặc khách phát sinh trước khi tích hợp, thì sử dụng hàm tạo mới khách hàng sau đó dựa trên dublicated_id phát sinh (nếu trùng) để thực hiện cập nhật

Cập nhật người dùng

PUT {{domain}/api/v1/contacts/{{contactId}}

Headers

Name

Type

Description

***

String

Thông tin xác thực chung

Request Body

Name

Type

Description

contact

Object

Cấu trúc object như ví dụ minh họa

{
    "code": "ok",
    "contact": {
        "phone_no": "024***22",
        "updated_at": "2023-04-12 14:54:24",
        "created_at": "2023-04-12 14:54:24",
        "id": 63216006,
        "email": "uyel**@**l.com",
        "username": "Le ***yen"
    }
}

Danh sách khách hàng

Là dữ liệu biến thiên theo ngày tháng. Sẽ tăng dần theo thời gian, Danh sách này có kết quả gồm số ít trường thông tin mang tính chất điển hình gồm ID, số điện thoại, họ tên, email ngày tạo. Dựa vào danh sách này có thể lấy thông tin đầy đủ và chi tiết cho 1 khách hàng bằng api Chi tiết khách hàng phía dưới

Mẫu tham khảo cấu hình POSTMAN lấy danh sách khách hàng

Danh sách khách hàng V2

Thông báo chuyển đổi API
API GET {{domain}}/api/v1/contacts sẽ kết thúc vào ngày 02/09/2026. Sau thời điểm này, hệ thống sẽ tự động chuyển sang endpoint V2 tương ứng:
Để tránh gián đoạn tích hợp, bạn nên chuyển sang V2 trước thời điểm trên. Trong giai đoạn chuyển đổi, API V1 vẫn có thể hoạt động nhưng sẽ được đánh dấu là deprecated.

Dữ liệu được cập nhật theo thời gian. Danh sách trả về một số trường thông tin cơ bản, điển hình như Phiên bản V2 vẫn giữ cấu trúc response gần tương tự V1 để thuận tiện chuyển đổi, đồng thời bổ sung các mốc thời gian thực tế sau khi hệ thống chuẩn hóa khoảng thời gian truy vấn.

Danh sách khách hàng V2

GET {{domain}}/api/v2/contacts

Query Parameters

Name

Type

Description

updated_since

DateTime (ISO8601)

Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ

updated_to

DateTime (ISO8601)

Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ

created_since

DateTime (ISO8601)

Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ

created_to

DateTime (ISO8601)

Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ

page

Int

Trang số. Mặc định 1

count

Int

Số bản ghi trên trang. Mặc định 50, tối đa theo cấu hình hệ thống

order_by

String

Sắp xếp theo trường dữ liệu. Hỗ trợ: id, username, email, email2, phone_no, phone_no2, phone_no3, facebook, gender, organization_id, created_at, updated_at. Mặc định created_at

order_type

String

Kiểu sắp xếp DESC hoặc ASC. Mặc định DESC

Headers

Name

Type

Description

***

String

Thông tin xác thực chung

Lưu ý khi sử dụng

Chỉ chấp nhận các query parameter nằm trong danh sách trên. Nếu truyền parameter ngoài whitelist, hệ thống trả về HTTP 400.
Nếu không có bất kỳ điều kiện ngày hợp lệ nào thuộc nhóm created_* hoặc updated_*, hệ thống sẽ trả về danh sách rỗng để tránh quét toàn bộ dữ liệu khách hàng.
Mỗi cặp điều kiện thời gian created_since/created_to hoặc updated_since/updated_to chỉ được xử lý trong phạm vi tối đa 31 ngày.

Quy tắc xử lý thời gian

Nếu truyền đủ created_since và created_to:
- Nếu khoảng thời gian không quá 31 ngày thì giữ nguyên.
- Nếu quá 31 ngày hoặc created_since >= created_to thì hệ thống tự chuẩn hóa thành created_since = created_to - 31 days.
Nếu chỉ truyền created_since, hệ thống tự bổ sung created_to = created_since + 31 days.
Nếu chỉ truyền created_to, hệ thống tự bổ sung created_since = created_to - 31 days.
Cặp updated_since/updated_to áp dụng quy tắc tương tự.
Giá trị ngày không đúng định dạng hoặc nằm ngoài phạm vi hợp lệ sẽ được hiểu như chưa truyền.

Kết quả điển hình

{
  "code": "ok",
  "numFound": 123,
  "created_since": "2026-07-01T00:00:00Z",
  "created_to": "2026-08-01T00:00:00Z",
  "updated_since": null,
  "updated_to": null,
  "contacts": [
    {
      "id": 1001,
      "username": "Nguyen Van A",
      "email": "a@example.com",
      "email2": null,
      "phone_no": "0900000000",
      "phone_no2": null,
      "phone_no3": null,
      "facebook": null,
      "gender": 0,
      "organization_id": null,
      "created_at": "2026-07-15 09:30:00",
      "updated_at": "2026-07-20 10:00:00"
    }
  ]
}

Mô tả kết quả

STT

Tên trường

Chú thích

code

Trạng thái thành công. ok: Thành công, errors: Thất bại

numFound

Số bản ghi tìm thấy theo điều kiện lọc

created_since

Thời điểm bắt đầu thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa

created_to

Thời điểm kết thúc thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa

updated_since

Thời điểm bắt đầu thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa

updated_to

Thời điểm kết thúc thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa

contacts[]

Mảng dữ liệu danh sách khách hàng

Cấu trúc từng phần tử trong contacts[] gồm các trường điển hình sau:

id: ID khách hàng
username: Họ tên khách hàng
email: Email chính
email2: Email thứ 2
phone_no: Số điện thoại thứ nhất
phone_no2: Số điện thoại thứ 2
phone_no3: Số điện thoại thứ 3
facebook: Facebook ID
gender: Giới tính
organization_id: ID tổ chức
created_at: Ngày tạo
updated_at: Ngày cập nhật

Ví dụ truy vấn

GET /api/v2/contacts?created_to=2026-07-31T00:00:00Z&page=1&count=50&order_by=created_at&order_type=DESC

Trong ví dụ trên, hệ thống sẽ tự chuẩn hóa khoảng thời gian và có thể trả về thêm các trường:

{
  "created_since": "2026-06-30T00:00:00Z",
  }
  
Trước ngày 02/09/2026, endpoint GET {{domain}}/api/v1/contacts vẫn có thể hoạt động 
để hỗ trợ quá trình chuyển đổi. Tuy nhiên, endpoint này đã được đánh dấu là deprecated.
 Khuyến nghị chuyển sang GET {{domain}}/api/v2/contacts sớm nhất có thể. 
 Sau ngày 02/09/2026, API V1 sẽ ngừng hoạt động. Nếu tiếp tục gửi yêu cầu đến V1, 
 hệ thống sẽ tự động chuyển sang V2.

Danh sách khách hàng (V1)

GET {{domain}/api/v1/contacts

API này sẽ ngừng hoạt động sau ngày 02/09/2026. Vui lòng chuyển sang V2 để tiếp tục sử dụng.

Query Parameters

Name

Type

Description

updated_since

DateTime (ISO8601)

Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ

updated_to

DateTime (ISO8601)

Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ

created_since

DateTime (ISO8601)

Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ

created_to

DateTime (ISO8601)

Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ

page

Int

Trang số

count

Int

Số bản ghi trên trang (Tối đa 500)

order_by

String

Sắp xếp theo trường dữ liệu (mặc định created_at)

order_type

String

Kiểu sắp xếp DESC hoặc ASC (Giảm dần hoặc tăng dần) Mặc định DESC

Headers

Name

Type

Description

***

String

Thông tin xác thực chung

{
    "code": "ok",
    "numFound": 3,
    "contacts": [
        {
            "id": 165027003,
            "created_at": "2023-04-14T09:43:24Z",
            "updated_at": "2023-04-14T09:43:24Z",
            "phone_no": "0334992975",
            "username": "0334992975"
        }, 
    ...
  ]
}

Stt

Tên trường

Chú thích

code

Trạng thái thành công: ok: Thành công errors: Thất bại

numFound

Số bản ghi tìm thấy theo điều kiện lọc

contacts []

Mảng dữ liệu danh sách khách hàng. Gồm các object có cấu trúc như sau

id: Id của khách hàng - Dùng ID này để truy xuất thông tin chi tiết, tham số {{contactId}}
username: Họ tên khách hàng
created_at: Ngày tạo
updated_at: Ngày cập nhật
phone_no: Số điện thoại thứ nhất của khách hàng

Chi tiết khách hàng

Dựa vào các hàm tạo mới hay cập nhật khách hàng hoặc danh sách khách hàng, trả về các {{contactId}}. Nhà phát triển sử dụng hàm này để lấy thông tin chi tiết 1 khách hàng. API này bắt buộc phải có contactID mới thực hiện được

Chi tiết khách hàng

GET {{domain}/api/v1/contacts/{{contactId}}

Headers

Name

Type

Description

***

String

Thông tin xác thực chung

{
    "code": "ok",
    "contact": {
        "id": 124921946,
        "username": "Nguyễn Văn Nam",
        "email": "demoapi@gmail.com",
        "email2": null,
        "phone_no": "0646546546546",
        "phone_no2": "09887456123",
        "phone_no3": null,
        "facebook": null,
        "gender": 1,
        "organization_id": 246080,
        "address": null,
        "city_id": null,
        "district_id": null,
        "created_at": "2021-10-30 00:16:04",
        "updated_at": "2023-04-24 17:56:13",
        "role_id": 3,
        "campaign_handler_id": null,
        "take_phone_at": "2022-04-12 14:30:00",
        "take_email_at": "2023-04-24 17:55:56",
        "custom_fields": [
                      {
                "id": 7492,
                "lable": "GIỚI TÍNH",
                "type": "Single drop-down list",
                "value": "33213"
            },
            {
                "id": 7584,
                "lable": "Tên trên QLBH",
                "type": "Text",
                "value": "AB"
            }
            ....           
          
        ],
        "organization": {
            "organization_id": 246080,
            "organization_domain": "323232",
            "organization_name": "sấ"
        }
    }
}
ta

STT

Tên trường

Ý nghĩa

code

Trạng thái ok: Thành công error: Lỗi

contact

Đối tượng thông tin khách hàng khách hàng (xem chi tiết ở bảng dưới)

Chi tiết đối tượng thông tin khách hàng (object)

STT

Tên trường

Ý nghĩa

ID khách hàng

username

Họ tên khách hàng

email2

Email 2

phone_no

Số điện thoại

phone_no2

Số điện thoại thứ 2

phone_no3

Số điện thoại 3

gender

Giới tính (0: Nam, 1 Nữ, 2: Không xác định)

organization_id

ID tổ chức

address

Địa chỉ

city_id

ID tỉnh/thành phố

district_id

ID huyện/Quận

created_at

Ngày tạo

updated_at

Ngày cập nhật

take_phone_at

Thời điểm thu thập số điện thoại

take_email_at

Thời điểm thu thập được email

custom_fields

Thông tin trường động (xem thêm ở Trường động (Custom fields))

organization

Tổ chức

zalo_id

Zalo ID

zalo_followers

Mảng dữ liệu object các Zalo Oa mà khách đang theo dõi nếu Zalo_id có giá trị. Trong đó: - oa_name: Tên Zalo OA - oa_id: ID OA, - active: Trạng thái tích hợp của OA (1: Đang kích hoạt, 0. Ngừng kích hoạt) - follow_status: Trạng thái follow của khách ( 1: Đang follow, null / 0: Không follow hoặc đã hủy) - updated_at: Ngày cập nhật mới nhất

facebook

ID facebook

psid

Mảng dữ liệu object các Facebook Page khách hàng đang theo dõi nếu trường facebook có giá trị. Trong đó - page_id: ID của page - psid: ID của khách trên page

Tìm khách hàng theo số điện thoại

Trong trường hợp cần tìm 1 khách hàng đã tồn tại hay chưa sử dụng API dưới đây, hệ thống sẽ trả về thông tin cơ bản của khách hàng.

Tìm khách hàng theo số điện thoại

GET {{domain}/api/v1/api/v1/contactsByPhone

Sử dụng parametter phoneNo để tìm khách hàng (Xem ảnh mô tả)

Query Parameters

Name

Type

Description

phoneNo*

String

Số điện thoại của khách hàng (Dạng 0XXXXX)

{
    "code": "ok",
    "contact": {
        "username": "A **",
        "id": 63150747,
        "email": "abc123@gmail.com",
        "phone_no": "09839**",
        "phone_no2": "0555****",
        "phone_no3": null,
        "email2": "****",
        "facebook": "546869858829726_2012787322172363",
        "gender": null,
        "organization_id": null,
        "created_at": "2020-01-17 10:12:18",
        "updated_at": "2023-06-24 16:54:10"
    }
}

{ "code": "errors", "message": "Not found user" }

PreviousDeal NextThông tin tỉnh/huyện/xã

Last updated 2 days ago