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
ticket_no
Số phiếu ghi
ticket_status
ticket_subject
Chủ đề phiếu ghi
ticket_priority
ticket_id
Id phiếu ghi, Khóa chính để thực hiện tương tác với phiếu ghi qua API
requester_id
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
assignee_id
Id người xử lý. Là Id của chuyên viên trong 1 hệ thống
created_at
Ngày tạo phiếu ghi
updated_at
Ngày cập nhật phiếu ghi
group_id
ticket_source
duedate
Hạn xử lý
satisfaction
Điểm hài lòng
satisfaction_at
Ngày đánh giá sự hài lòng
satisfaction_send
Ngày gửi đánh giá hài lòng
satisfaction_content
Nội dung đánh giá hài lòng
campaign_id
ID chiến dịch, xem danh sách chiến dịch
automessage_id
ID Chiến dịch tự động
is_overdue
Trạng thái quá hạn xử lý
incident_id
service_id
ID dịch vụ, xem danh sách dịch vụ
ticket_source_detail_id
ID nguồn chi tiết của phiếu ghi
comments
[1] Danh sách bình luận trên phiếu ghi
custom_filed
[2] Danh sách trường động và giá trị được lưu trữ cho phiếu ghi
assignee
[3] Đối tượng người xử lý
requester
[4] Đối tượng người yêu cầu
tags
Danh sách các thẻ được gắn
ccs
[5] Danh sách các người dùng được cc
follows
[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
**
Request Body
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)
ticket.district_id
String(4)
ticket.address
String(255)
Địa chỉ của người yêu cầu
ticket.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[]
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
tickets.campaign_id
Int
ID chiến dịch
tickets.member_status_id
Int
tickets.ref_url
String
Địa chỉ nguồn phát sinh dữ liệu ví dụ trang web đặt form
Chi tiết các trường dữ liệu
code
string
"ok": thành công, "nok": thất bại
ticket
Object
Đối tượng phiếu ghi tạo thành công
ticket.updated_at
DateTime
Ngày cập nhật
ticket.created_at
DateTime
Ngày tạo
ticket.ticket_no
Int
Số phiếu ghi
ticket.ticket_id
Int
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
Cập nhật phiếu ghi
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
***
String
Request Body
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
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.
ticket.member_status_id
Int
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.
Văn bản text (độ dài tối đa 255 ký tự)
Kiểu số
Kiểu ngày tháng, định dạng YYYY/MM/DD
Kiểu chọn 1 giá trị
Kiểu chọn nhiều giá trị
Kiểu văn bản với giao diện hiển thị mở rộng
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ị
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
***
String
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
***
String
Request Body
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)
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ệnupdated_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
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
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
***
String
Last updated