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.

Last updated 1 month ago

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

STT

Tên trường

Kiểu dữ liệu

Chú thích

Thêm mới, cập nhật 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

Name

Type

Description

Request Body

Name

Type

Description

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

STT

Tên trường

Kiểu

Ghi chú

JSON body tạo ticket

{
    "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",
        "duedate":"2023-06-01 20:00:00",
        "is_public":0        
    }
}

Thông báo lỗi sai cú pháp

{
    "code": "errors",
    "message": "Invalid Format"
}

Thông báo lỗi sai ID của người xử lý

{
"code": "errors",
"message": "invalid value: assignee_id"
}

Sai api token

{
    "code": "errors",
    "message": "Authorization header is incorrect"
}

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

{
    "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",
        "duedate":"2023-06-01 20:00:00",
        "is_public": 1
    }
}

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

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

Name

Type

Description

Request Body

Name

Type

Description

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

{
    "ticket": {
        "ticket_subject": "Test",
        "ticket_comment": {
            "body": "Comment",
            "is_public": 1,
            "author_id": 124734559
        },
        "ticket_priority": "Hight",
        "ticket_source": "Voice",
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

Lỗi sai tác giả

{
    "code": "errors",
    "message": "invalid value: author_id"
}

Lỗi ID phiếu ghi không tồn tai

{
    "code": "errors",
    "message": "Ticket is not exist"
}

{
    "code": "errors",
    "message": "unsolved_incidents_ticket",
    "extraDataJson": {
        "unsolved_incidents_ticket_id": [
            474842751
        ]
    }
}

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.

STT

Kiểu

Ghi chú

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

Name

Type

Description

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

Name

Type

Description

Request Body

Name

Type

Description

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

1. Lỗi chưa có cặp điều kiện bắt buộc Request required [updated_since/updated_to] or [created_since/created_to] 2. Lỗi thiếu một trong các param hoặc dữ liệu điền trong các param không hợp lệ Định dạng phải là "YYYY-MM-DDTHH:mm:ssZ Request required [updated_since/updated_to] Request required [created_since/created_to] 3. Lỗi từ ngày/ đến ngày quá 31 ngày hoặc từ ngày lớn hơn tới ngày created_since must older than created_to and max 31 days 4. Lỗi filterID không thể lấy dữ liệu (thường là các filter ID có cấu hình động theo người dùng đăng nhập Can't get this filter!

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

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
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
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.
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

Name

Type

Description

Request Body

Name

Type

Description

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

Name

Type

Description

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


    }
}