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

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

Request Body

200: OK Thành công

Phản hồi thành công

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

Mẫu json gửi đi

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

400: Bad Request Lỗi sai định dạng (kiểm tra cấu trúc JSON gửi đi sai cú pháp)

Sai cú pháp

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

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

Sai thông tin

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

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

500: Internal Server Error

401: Unauthorized

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

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

postman

Mẫu body json

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

Phản hồi 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
    }
}

Cập nhật phiếu ghi

Mẫu body json

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

Request Body

200: OK Thành công

Phản hồi thành công

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

Mẫu param gửi đi

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

400: Bad Request Thất bại

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

401: Unauthorized Sai token

400 Lỗi phiếu ghi con chưa solved

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

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

200: OK

Kết quả thành công

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

Mô tả kết quả

[1] Chi tiết dữ liệu trường động

401: Unauthorized

404: Not Found

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

Request Body

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

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

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

Mô tả kết quả

Chi tiết 1 đối tượng phiếu ghi trong mảng tickets

401: Unauthorized

403: Forbidden

500: Internal Server Error

400: Bad Request Thông báo lỗi điều kiện đầu vào

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

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

Request Body

200: OK Thành công

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

400: Bad Request Lỗi thông tin đầu vào

403: Forbidden Lỗi xác thực

500: Internal Server Error Lỗi máy chủ

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

200: OK Thông tin thành công

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

{
    "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 ([e-mail])<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
        }


    }
}

Mô tả kết quả

404: Not Found

403: Forbidden Lỗi xác thực

500: Internal Server Error Lỗi máy chủ

400: Bad Request Lỗi thông tin đầu vào