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ú
1	id	INT	ID của người dùng
2	username	TEXT(255)	Họ tên
3	email	EMAIL	Email người dùng
4	email2	EMAIL	Email thứ 2
5	phone_no	TELEPHONE	Số điện thoại của người dùng
6	phone_no2	TELEPHONE	Số điện thoại thứ 2
7	phone_no3	TELEPHONE	Số điện thoại thứ 3
8	created_at	DATETIME	Ngày tạo
9	updated_at	DATETIME	Ngày cập nhật.
10	created_from	INT	Nguồn tạo (Xem danh sách nguồn) Cột Source ID
11	organization_id	INT	ID tổ chức
12	organization	TEXT(255)	Tên tổ chức
13	city_id	INT	ID thành phố (Tham khảo danh sách tỉnh thành)
14	district_id	INT	ID huyện/quận
15	address	TEXT(255)	Địa chỉ
16	gender	INT	Giới tính: 0. Nam, 1 Nữ, 2 Không xác định
17	facebook	INT	ID facebook (De-precade)
18	campaign_handler_id	INT	ID chiến dịch xử lý
19	custom_fields	ARRAY	Danh sách trường động
20	follower_id	INT	Id của chuyên viên quản lý (xem Chuyên viên Trường ID
21	take_phone_at	DATETIME	Thời điểm thu thập được số điện thoại (Null hoặc Ngày tháng)
22	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

200: OK

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

{
    "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"
    }
}

Mô tả trường thông tin điển hình

STT	Tên trường	Kiểu	Ý nghĩa
1	code	String	"ok": Thành công, "errors": Thất bại
2	contact	Object	Đối tượng thông tin khách hàng được tạo mới
3	contact.id	Int
4	contact.phone_no	String	Số điện thoại
5	contact.email	Email	Email
6	contact.username	String	Họ tên khách hàng
7	contact.created_at		Ngày tạo
8	contact.updated_at		Ngày cập nhật

400: Bad Request

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

Trùng email

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

Trùng số điện thoại

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

500: Internal Server Error

401: Unauthorized

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

200: OK

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

{
    "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"
    }
}

400: Bad Request

500: Internal Server Error

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

GET {{domain}/api/v1/contacts

Query Parameters

Name	Type	Description
updated_since	DateTimeTZ	Có thời điểm cập nhật từ ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)
updated_to	DateTimeTZ	Có thời điểm cập nhật đến ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)
created_since	DateTimeTZ	Có thời điểm tạo từ ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)
created_to	DateTimeTZ	Có thời điểm tạo từ ngày (Kiểu dữ liệu 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

200: OK Kết quả thành công

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

{
    "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"
        }, 
    ...
  ]
}

Second Tab

Stt	Tên trường	Chú thích
1	code	Trạng thái thành công: ok: Thành công errors: Thất bại
2	numFound	Số bản ghi tìm thấy theo điều kiện lọc
3	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

200: OK Thành công

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

{
    "code": "ok",
    "contact": {
        "id": 124921946,
        "username": "Nguyễn Văn Nam",
        "email": "[e-mail]",
        "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

Cấu trúc dữ liệu

STT	Tên trường	Ý nghĩa
1	code	Trạng thái ok: Thành công error: Lỗi
2	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
1	id	ID khách hàng
2	username	Họ tên khách hàng
3	email	Email
4	email2	Email 2
5	phone_no	Số điện thoại
6	phone_no2	Số điện thoại thứ 2
7	phone_no3	Số điện thoại 3
8	gender	Giới tính (0: Nam, 1 Nữ, 2: Không xác định)
9	organization_id	ID tổ chức
10	address	Địa chỉ
11	city_id	ID tỉnh/thành phố
12	district_id	ID huyện/Quận
13	created_at	Ngày tạo
14	updated_at	Ngày cập nhật
15	take_phone_at	Thời điểm thu thập số điện thoại
16	take_email_at	Thời điểm thu thập được email
17	custom_fields	Thông tin trường động (xem thêm ở Trường động (Custom fields))
18	organization	Tổ chức
19	zalo_id	Zalo ID
20	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
21	facebook	ID facebook
22	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.

(Mẫu Postman tham khảo)

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)

200: OK Kết quả thành công

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

{
    "code": "ok",
    "contact": {
        "username": "A **",
        "id": ,
        "email": "[e-mail]",
        "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"
    }
}

404: Not Found Không tìm thấy dữ liệu

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

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