Phiếu ghi

Cập nhật, Thêm mới, Danh sách phiếu ghi, chi tiết và các thuộc tính của phiếu ghi.

Các trường thông tin của phiếu ghi

Phiếu ghi trên hệ thống CareSoft là 1 đối tượng dữ liệu được tạo ra bởi tất cả các kênh tương tác mà hệ thống đa kênh có thể thu nhận được. Mọi tương tác của khách hàng tới hệ thống đều tạo ra phiếu ghi và lưu trữ thông tin của nó.

Các trường thông tin của phiếu ghi

STTTên trườngKiểu dữ liệuChú thích
1

ticket_no

Int

Số phiếu ghi

2

ticket_status

String

Trạng thái phiếu ghi có

3

ticket_subject

String (255)

Chủ đề phiếu ghi

4

ticket_priority

String

Độ ưu tiên có

5

ticket_id

Int

Id phiếu ghi, Khóa chính để thực hiện tương tác với phiếu ghi qua API

6

requester_id

Int

Id người yêu cầu, khóa chính để thực hiện tương tác với khách hàng qua API

7

assignee_id

Int

Id người xử lý. Là Id của chuyên viên trong 1 hệ thống

8

created_at

DateTime

Ngày tạo phiếu ghi

9

updated_at

DateTime

Ngày cập nhật phiếu ghi

10

group_id

Int

Bộ phận của người xử lý (có thể lấy danh sách bộ phận tại đây

11

ticket_source

String

Nguồn phiếu ghi, xem danh sách

12

duedate

DateTime

Hạn xử lý

13

satisfaction

Int

Điểm hài lòng

14

satisfaction_at

DateTime

Ngày đánh giá sự hài lòng

15

satisfaction_send

DateTime

Ngày gửi đánh giá hài lòng

16

satisfaction_content

String

Nội dung đánh giá hài lòng

17

campaign_id

Int

ID chiến dịch, xem danh sách chiến dịch

18

automessage_id

Int

ID Chiến dịch tự động

19

is_overdue

Int

Trạng thái quá hạn xử lý

20

incident_id

Int

ID

21

service_id

Int

ID dịch vụ, xem danh sách dịch vụ

22

ticket_source_detail_id

Int

ID nguồn chi tiết của phiếu ghi

23

comments

Array

[1] Danh sách bình luận trên phiếu ghi

24

custom_filed

Array

[2] Danh sách trường động và giá trị được lưu trữ cho phiếu ghi

25

assignee

Object

[3] Đối tượng người xử lý

26

requester

Object

[4] Đối tượng người yêu cầu

27

tags

Array

Danh sách các thẻ được gắn

28

ccs

Array

[5] Danh sách các người dùng được cc

29

follows

Array

[6] Danh sách người dùng theo dõi

Thêm mới, cập nhật phiếu ghi

Thêm mới phiếu ghi

Thêm mới phiếu ghi

POST {{domain}}/api/v1/tickets

Sử dụng hàm này để thêm mới 1 phiếu ghi đồng thời thực hiện giao phiếu cho một chuyên viên chỉ định hoặc một phòng ban bất kỳ.

Headers

NameTypeDescription

**

Thông tin xác thực chung

Request Body

NameTypeDescription

ticket

object

Đối tượng phiếu ghi

ticket.username

String

Tên người yêu cầu

ticket.phone*

Phone

ticket.city_id

String(4)

ID của thành phố của người yêu cầu (Xem ở api Thông tin tỉnh/huyện).

ticket.district_id

String(4)

ID của quận/huyện người yêu cầu (Xem ở api Thông tin tỉnh/huyện)

ticket.address

String(255)

Địa chỉ của người yêu cầu

ticket.email

Email

(*) Email người yêu cầu

ticket.ticket_subject

String(255)

Tiêu đề phiếu ghi

ticket.ticket_comment

String

Ghi chú của phiếu ghi

ticket.assignee_id*

Int

ticket.group_id

Int

(**) ID của phòng ban được chia phiếu ghi

ticket.service_id

Int

ticket.custom_fields

Array[]

Mảng truyền dữ liệu trường động phiếu ghi

ticket.requester_id

Int

Id của người yêu cầu

ticket.ref_url

URL

ticket.is_public

Int

Trạng thái ghi chú hoặc phản hồi

ticket.duedate

DateTime

Thời hạn xử lý

tickets.follow_user

String

Danh sách ID của chuyên viên theo dõi phiếu ghi, cách nhau bởi dấu phẩy

tickets.ticket_status

String

Trạng thái phiếu ghi. Một trong 5 trạng thái ("new", "open","solved","closed", "pending")

tickets.ticket_priority

String

Độ ưu tiên là một trong 4 giá trị "High","Low","Normal","Urgent"

tickets.cc_user

String

Danh sách ID của khách hàng CC phiếu ghi, cách nhau bởi dấu phẩy

Phiếu ghi tạo thành công 
{
    "code": "ok",
    "ticket": {
        "updated_at": "2023-03-28 13:55:23",
        "ticket_subject": "Test create ticket from API",
        "ticket_no": 7016,
        "created_at": "2023-03-28 13:55:23",
        "ticket_id": 381185209,
        "requester_id": 126564055
    }
}

Chi tiết các trường dữ liệu

STTTên trườngKiểuGhi chú
1

code

string

"ok": thành công, "nok": thất bại

2

ticket

Object

Đối tượng phiếu ghi tạo thành công

3

ticket.updated_at

DateTime

Ngày cập nhật

4

ticket.created_at

DateTime

Ngày tạo

5

ticket.ticket_no

Int

Số phiếu ghi

6

ticket.ticket_id

Int

7

requester_id

Int

Nếu bạn đã có ID của người dùng bạn có thể truyền requester_id mà không cần gửi email, số điện thoại.

Hệ thống CareSoft sử dụng số điện thoại và email làm khóa duy nhất do đó sẽ luôn tạo phiếu ghi cho 1 người nếu bạn chỉ thay đổi tên người dùng

Mẫu code 

curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/tickets' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "ticket": {
        "phone": "0900000001",
        "username": "Khách hàng Demo",
        "service_id": 12,
        "ticket_subject": "Test create ticket from API",
        "ticket_comment": "Coment create ticket from Api  ",
        "ref_url": "https://caresoft.vn?utm=xtest",
        "is_public": 1
    }
}'

Cập nhật phiếu ghi

{
    "ticket": {
        "ticket_subject": "Test",
        "ticket_comment": {
            "body": "Cập nhật giá trị mua hành thành giao hàng",
            "is_public": 1,
            "author_id": 124734559
        },
        "ticket_priority": "Hight",
        "ticket_source": "Voice",
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

Biểu mẫu trên sẽ cập nhật phiếu ghi và 1 giá trị trường động

Cập nhật phiếu ghi

PUT {{domain}}/api/v1/tickets/{{ticketId}}

Cập nhật thông tin vào một phiếu ghi hiện hữu cần ID của phiếu ghi theo biến {{ticketId}}.

Headers

NameTypeDescription

***

String

Thông tin xác thực chung

Request Body

NameTypeDescription

ticket*

Object

Đối tượng phiếu ghi

ticket.ticket_subject

String

Tiêu đề phiếu ghi (nếu cần sửa)

ticket.ticket_comment*

Object

Đối tượng ghi chú cho phiếu ghi.

ticket.ticket_comment.body*

String

Nội dung comment

ticket.ticket_comment.is_public

Int

ticket.ticket_comment.author_id*

Int

(*)

ticket.ticket_priority

String

(*) Độ ưu tiên của phiếu ghi có các trạng thái : Low, High, Normal

ticket.custom_fields

Array

Mảng thông tin trường động, xem thêm ở đây

ticket.assignee_id

Int

Id của chuyên viên (trong trường hợp cần đổi chuyên viên của phiếu ghi)

ticket.solved_incidents

Boolean

True/False (Mặc định True) Trong trường hợp truyền vào là False và ticket_status="Solved". Hệ thống sẽ kiểm tra phiếu ghi con liên quan nếu còn phiếu chưa solved sẽ trả về lỗi 400 kèm danh sách phiếu ghi chưa solved unsolved_incidents_ticket_id.

{
    "code": "ok",
    "ticket": {
        "updated_at": "2023-03-29 17:18:40",
        "ticket_subject": "Test",
        "ticket_no": 7043,
        "created_at": "2023-03-29 13:25:31",
        "ticket_id": 381440615
    }
}

Danh sách trường động phiếu ghi

Trường động được cấu hình trên giao diện CareSoft. Có 7 kiểu dữ liệu cho trường động phiếu ghi.

Chi tiết các kiểu dữ liệu của trường động phiếu ghi.

STTKiểuGhi chú
1
TEXT

Văn bản text (độ dài tối đa 255 ký tự)

2
NUMBER

Kiểu số

3
DATE

Kiểu ngày tháng, định dạng YYYY/MM/DD

4
SINGLE DROP-DOWN LIST

Kiểu chọn 1 giá trị

5
MULTIPLE SELECT DROP-DOWN LIST

Kiểu chọn nhiều giá trị

6
TEXT AREA

Kiểu văn bản với giao diện hiển thị mở rộng

7
STAGE

Kiểu trạng thái stage, là dạng chọn 1 giá trị tương đương kiểu chọn 1 giá trị

8
LINK

Kiểu địa chỉ website, định dạng http:// hoặc https://

Lưu ý: Trường động phiếu ghi có thể được bật/ tắt hoặc thay đổi kiểu từ giao diện hệ thống CareSoft, cần đồng bộ định kỳ hàng ngày để đảm bảo các cấu hình thông tin giữa các hệ thống thông suốt.

Danh sách trường động phiếu ghi

GET {{domain}}/api/v1/tickets/custom_fields

Headers

NameTypeDescription

***

String

Thông tin xác thực chung

Mẫu kết quả điển hình
{
  "code": "ok",
  "custom_fields": [
    {
      "custom_field_id": 5159,
      "custom_field_lable": "Ghi chú của",
      "type": "Text Area"
    },
    {
      "custom_field_id": 5160,
      "custom_field_lable": "Chi tiết sản phẩm",
      "type": "Single drop-down list",
      "values": [
        {
          "id": 110725,
          "lable": "Sách ô ly",
          "parent_value_id": 106473
        },
        {
          "id": 110726,
          "lable": "Sách 2",
          "parent_value_id": 106473
        },
        {
          "id": 110727,
          "lable": "Bút bi",
          "parent_value_id": 106474
        },
        {
          "id": 110728,
          "lable": "Bút mực",
          "parent_value_id": 106474
        }
      ]
    }
  ]
}

Danh sách phiếu ghi

Tùy theo từng nghiệp vụ nhà phát triển có thể sử dụng các param CareSoft cung cấp để lọc các phiếu ghi phát sinh trong quá trình hoạt động.

1. Danh sách phiếu ghi

(Phiên bản V2)

Lưu ý: API Danh sách phiếu ghi bắt buộc phải có 1 trong hai cặp parameter [created_since/created_to] Hoặc [updated_since/updated_to] và thời gian không quá 31 ngày.

Trong trường hợp tất cả các param đều được điền dữ liệu thì cặp [updated_since/updated_to] được ưu tiên. Định dạng dữ liệu dạng Năm-Tháng-NgàyTGiờ:Phút:GiâyZ Ví dụ: created_since=2023-06-26T00:00:00Z Các hệ thống đang tích hợp cần bổ sung điều kiện tìm kiếm để đáp ứng. Thông báo lỗi sẽ trả về mã lỗi "errors" và param đính kèm ( Xem thêm trong phần Response của API phía dưới: Lỗi 400)

V2- Lấy danh sách phiếu ghi

GET {{domain}}/api/v2/tickets

Danh sách phiếu ghi và các điều kiện lọc danh sách phiếu ghi qua API

Headers

NameTypeDescription

***

String

Thông tin xác thực chung

Request Body

NameTypeDescription

created_since

DateTimeTZ

Ngày tạo từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ

created_to

DateTimeTZ

Ngày tạo tới, định dạng YYYY-mm-ddTHH:mm:ssZ

updated_since*

DateTimeTZ

Ngày cập nhật từ, định dạng YYYY-mm-ddTHH:mm:ssZ

updated_to*

DateTimeTZ

Ngày cập nhật tới, định dạng YYYY-mm-ddTHH:mm:ssZ

requester_id

Int

ID người yêu cầu

assignee_id

Int

ID người xử lý

service_id

Int

ID dịch vụ

page

Int

Trang số

count

Int

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

filter_id

Int

ID bộ lọc (Không khả dụng với các bác bộ lọc có tham số người dùng đăng nhập hay bộ phận của người dùng đăng nhập)

{
    "code": "ok",
    "numFound": 414,
    "tickets": [
        {
            "ticket_no": 7464,
            "ticket_status": "new",
            "ticket_subject": "Cuộc gọi ra gặp khách hàng tới ****",
            "created_at": "2023-04-24T17:01:35Z",
            "updated_at": "2023-04-24T17:01:52Z",
            "ticket_source_end_status": 0,
            "ticket_source": "Voice Out",
            "ticket_priority": "Normal",
            "service_id": 20043428,
            "ticket_id": 387792628,
            "requester_id": 165802327,
            "assignee_id": 162712234,
            "custom_fields": [              
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....                
                                                              
                 
            ],
            "assignee": {
                "id": 162712234,
                "username": "ltvyy",
                "email": "****m",
                "phone_no": "0****",
                "agent_id": "50027",
                "role_id": 2,
                "group_id": 14181,
                "group_name": "ORV"
            },
            "requester": {
                "id": 165802327,
                "username": "09326****",
                "email": null,
                "phone_no": "0932****",
                "organization_id": null
            },
            "tags": [],
            "ccs": [],
            "follows": []
        },
    ...
  ]
}

2. Danh sách phiếu ghi

(Phiên bản 1)

Lưu ý: Một thuật toán tối ưu lệnh tìm kiếm phiếu ghi sẽ được thực hiện theo mô hình sau

  1. Khi gọi API không cung cấp khoảng ngày kết thúc (chỉ truyền ngày bắt đầu: created_since hoặc updated_since). Mà ngày bắt đầu trước ngày hiện tại hơn 31 ngày thì hệ thống sẽ tự động chọn khoảng ngày kết thúc là ngày hiện tại và trả về kết quả trong 31 ngày tính từ ngày hiện tại. Nếu ngày bắt đầu nhỏ hơn ngày hiện tại dưới 31 ngày thì hệ thống giữ nguyên ngày bắt đầu và tiến hành lọc dữ liệu theo tham số trên

  2. Khi gọi API cung cấp khoảng ngày kết thúc (param: created_to hoặc updated_to). Mà ngày kết thúc sau ngày bắt đầu quá 31 ngày thì hệ thống tự chọn lại khoảng ngày bắt đầu bằng ngày kết thúc - 31 ngày

  3. Khi gọi API cung cấp cả hai tham số Bắt đầu và Kết thúc cách nhau không quá 31 ngày thì hệ thống lọc phiếu ghi theo giá trị truyền vào này và trả về kết quả tương ứng.

  4. Trong trường hợp cặp điều kiện created_since và updated_since đều được cung cấp hệ thống sẽ ưu tiên xử lý theo điều kiện updated_since

V1- Lấy danh sách phiếu ghi

GET {{domain}}/api/v1/tickets

Danh sách phiếu ghi và các điều kiện lọc danh sách phiếu ghi qua API, Bắt buộc phải có 1 tham số created_since hoặc updated_since

Headers

NameTypeDescription

****

Thông tin xác thực chung

Request Body

NameTypeDescription

created_since*

DateTimeTZ

Ngày tạo từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ

created_to

DateTimeTZ

Ngày tạo đến lúc, định dạng YYYY-mm-ddTHH:mm:ssZ

updated_since*

DateTimeTZ

Ngày cập nhật từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ

updated_to

DateTimeTZ

Ngày cập nhật đến lúc, định dạng YYYY-mm-ddTHH:mm:ssZ

assignee_id

Int

ID người xử lý

service_id

Int

ID dịch vụ

page

Int

Trang số (Mặc định 1)

count

Int

Số bản ghi trên trang (Mặc định 50 tối đa 500)

filter_id

Int

ID bộ lọc (Không khả dụng với các bác bộ lọc có tham số người dùng đăng nhập hay bộ phận của người dùng đăng nhập)

requester_id

Int

ID người yêu cầu

{
    "code": "ok",
    "numFound": 414,
    "tickets": [
        {
            "ticket_no": 7464,
            "ticket_status": "new",
            "ticket_subject": "Cuộc gọi ra gặp khách hàng tới ****",
            "created_at": "2023-04-24T17:01:35Z",
            "updated_at": "2023-04-24T17:01:52Z",
            "ticket_source_end_status": 0,
            "ticket_source": "Voice Out",
            "ticket_priority": "Normal",
            "service_id": 20043428,
            "ticket_id": 387792628,
            "requester_id": 165802327,
            "assignee_id": 162712234,
            "custom_fields": [              
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....                
                                                              
                 
            ],
            "assignee": {
                "id": 162712234,
                "username": "ltvyy",
                "email": "****m",
                "phone_no": "0****",
                "agent_id": "50027",
                "role_id": 2,
                "group_id": 14181,
                "group_name": "ORV"
            },
            "requester": {
                "id": 165802327,
                "username": "09326****",
                "email": null,
                "phone_no": "0932****",
                "organization_id": null
            },
            "tags": [],
            "ccs": [],
            "follows": []
        },
    ...
  ]
}

Chi tiết phiếu ghi

Dựa trên danh sách phiếu ghi, hoặc việc tạo, cập nhật các phiếu ghi, nhà phát triển có được ID của phiếu ghi. được định danh là "ticketId"

Lấy chi tiết thông tin phiếu ghi

GET {{domain}}/api/v1/tickets/{{ticketId}}

Lấy về thông tin chi tiết 1 phiếu ghi theo {{ticketId}}

Headers

NameTypeDescription

***

String

Thông tin xác thực chung 

{
    "ticket": {
        "account_id": 8187,
        "ticket_id": 387792628,
        "sla_id": 8113,
        "ticket_no": 7464,
        "requester_id": 165802327,
        "group_id": 14181,
        "ticket_source_end_status": 0,
        "assignee_id": 162712234,
        "ticket_priority": "Normal",
        "ticket_source": "Voice Out",
        "ticket_status": "new",
        "ticket_subject": "Cuộc gọi ra gặp khách hàng tới 0932****",
        "created_at": "2023-04-24 17:01:35",
        "updated_at": "2023-04-24 17:01:52",
        "solved": "2023-04-24 17:01:52",
        "duedate": null,
        "satisfaction": null,
        "satisfaction_at": null,
        "satisfaction_send": null,
        "satisfaction_content": null,
        "campaign_id": null,
        "automessage_id": null,
        "feedback_status": "ANSWERED_CALL",
        "is_overdue": null,
        "incident_id": null,
        "service_id": 20043428,
        "ticket_source_detail_id": 85041,
        "qa_agent": 126642807,
        "qa_script_id": 341,
        "current_agent": 124733804,
        "comments": [
            {
                "id": 933864241,
                "comment": "<b>Cuộc gọi ra</b><br/>Người gọi ra: ltvyy (156@gmail.com)<br/>ID cuộc gọi: 20230424170134-OUTOLTHV-935954<br/>Số điện thoại gọi tới: 093xxx<br/>Đầu số gọi ra: xxxx<br/>Thời gian bắt đầu: 2023-04-24 17:01:34<br/>Khách hàng trả lời cuộc gọi<br/>Thời gian trả lời: 2023-04-24 17:01:37<br/>Agent kết thúc cuộc gọi<br/>Thời gian kết thúc: 2023-04-24 17:01:52<br/>Thời lượng cuộc gọi: 00:00:15",
                "commentator_id": 162712234,
                "commentator_name": "ltvyy",
                "comment_source": "Voice Out",
                "call_id": "20230424170134-OUTOLTHV-935954",
                "created_at": "2023-04-24 17:01:35",
                "is_public": 1,
                "addition_details": null,
                "call_info": {
                    "start_time": "2023-04-24 17:01:34",
                    "end_time": "2023-04-24 17:01:51",
                    "called": "842871****",
                    "caller": "09326***",
                    "call_id": "20230424170134-OUTOLTHV-935954"
                }
            }
        ],
        "custom_filed": [
            
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....  
        ],
        "assignee": {
            "id": 162712234,
            "username": "ltvyy",
            "email": "1****",
            "phone_no": "01****",
            "agent_id": "50027",
            "role_id": 1,
            "group_id": 14181,
            "group_name": "ORV"
        },
        "requester": {
            "id": 165802327,
            "username": "09326****",
            "email": null,
            "phone_no": "09326*****",
            "organization_id": null
        },
        "tags": [],
        "ccs": [],
        "follows": [],
        "sla": "2d 06:23",     
        "qa_script": {
            "id": 481,
            "name": "Điểm âm đúng sai",
            "description": "Điểm âm đúng sai",
            "created_at": "2023-05-27 00:10:32",
            "updated_at": "2023-05-27 00:10:32"
        },
        "qa_result": {
            "updated_at": "2023-06-24 02:55:45",
            "is_agree": null,
            "agent_comment": null,
            "agent_comment_time": null,
            "is_lead_agree": null,
            "qa_lead_id": null,
            "qa_lead_name": null,
            "qa_lead_comment": null,
            "qa_comment_time": null,
            "rate": -27,
            "lstQuestions": [
                {
                    "field": "qa_field1",
                    "info": "kí tự",
                    "type": 0,
                    "rate_type": 1,
                    "rate_point": 0,
                    "comment": ""
                },
                {
                    "field": "qa_field2",
                    "info": "số",
                    "type": 1,
                    "rate_type": 1,
                    "rate_point": -1,
                    "comment": ""
                },
                {
                    "field": "qa_field3",
                    "info": "nt",
                    "type": 2,
                    "rate_type": 1,
                    "rate_point": 10,
                    "comment": null
                },
                {
                    "field": "qa_field4",
                    "info": "chọn1pa",
                    "type": 3,
                    "rate_type": -1,
                    "lstOptions": [
                        {
                            "id": 6901,
                            "description": "a1",
                            "point": -100
                        },
                        {
                            "id": 6902,
                            "description": "a1",
                            "point": -50
                        }
                    ],
                    "rate_point": -50
                },
                {
                    "field": "qa_field5",
                    "info": "chon n",
                    "type": 4,
                    "rate_type": -1,
                    "lstOptions": [
                        {
                            "id": 6903,
                            "description": "n1",
                            "point": -4
                        },
                        {
                            "id": 6904,
                            "description": "n2",
                            "point": -10
                        },
                        {
                            "id": 6905,
                            "description": "n3",
                            "point": 5
                        },
                        {
                            "id": 6906,
                            "description": "n4",
                            "point": 8
                        }
                    ],
                    "rate_point": 4
                },
                {
                    "field": "qa_field6",
                    "info": "vban",
                    "type": 6,
                    "rate_type": 1,
                    "rate_point": 10,
                    "comment": ""
                }
            ]
        },
        "qa_agent_name": {
            "username": "QA Test",
            "id": 126642807
        },
        "qa_current_agent": {
            "username": "Admin",
            "id": 124734559
        }


    }
}
PreviousDịch vụNextDanh sách nguồn

Last updated