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

STTTên trườngKiểu dữ liệuGhi 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

NameTypeDescription

**

String

Thông tin xác thực chung

Request Body

NameTypeDescription

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

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

NameTypeDescription

***

String

Thông tin xác thực chung

Request Body

NameTypeDescription

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

GET {{domain}/api/v1/contacts

Query Parameters

NameTypeDescription

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

NameTypeDescription

***

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

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

NameTypeDescription

***

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

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

NameTypeDescription

phoneNo*

String

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

{
    "code": "ok",
    "contact": {
        "username": "A **",
        "id": ,
        "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"
    }
}
PreviousNguồn chi tiếtNextThông tin tỉnh/huyện

Last updated