21. API Get thống kê số cuộc gọi & Thời gian làm việc của nhân viên
API Get thống kê số cuộc gọi & Thời gian làm việc của nhân viên
Tổng quan
Tài liệu mô tả 2 endpoint báo cáo dành cho hệ thống AntRing: thống kê cuộc gọi vào/ra theo nhân viên theo ngày, và thống kê thời gian làm việc (online / bật nhận lead) theo nhân viên theo ngày. Cả hai endpoint đều xác thực bằng header apikey, org được suy ra tự động từ apikey.
1. Thống kê cuộc gọi vào/ra theo nhân viên theo ngày
Endpoint: GET /apiring/reports/calls/by-user-daily
Đếm số cuộc gọi vào (inbound) / gọi ra (outbound) mà mỗi nhân viên thực hiện, nhóm theo từng ngày (giờ Việt Nam, UTC+7). Nguồn dữ liệu: Note có eventCode = 'eventnote.CONTACT_CALL'.
Auth: header apikey (org được xác định tự động theo apikey, không cần truyền org)
Query params
Tham số
Bắt buộc
Kiểu
Mô tả
dateStart
✅
ISO date string
Mốc bắt đầu (dùng $gt, không bao gồm chính mốc này)
dateEnd
✅
ISO date string
Mốc kết thúc (dùng $lt, không bao gồm chính mốc này)
userIds
❌
string, phân tách ,
Lọc theo danh sách _id nhân viên (Mongo ObjectId). Bỏ trống = lấy tất cả nhân viên trong org
Ràng buộc
● dateStart/dateEnd phải parse được thành ngày hợp lệ, nếu không trả 400.
● Khoảng cách dateEnd - dateStart tối đa 90 ngày, vượt quá trả 400.
● Nếu userIds có giá trị nhưng không có id nào hợp lệ → 400.
Response 200
users được sắp xếp theo totalCalls giảm dần. byDate (cả trong users[] và totalByDate) sắp xếp tăng dần theo date.
Response lỗi
Status
message
Nguyên nhân
400
ERROR: Filter time is wrong
Thiếu hoặc sai định dạng dateStart/dateEnd
400
ERROR: Filter time within 90 days
Khoảng ngày vượt quá 90 ngày
400
ERROR: User ids are invalid
userIds có nhưng không hợp lệ
500
ERROR
Lỗi hệ thống
Ví dụ
Ngày 28/08/2026 giờ VN, 1 nhân viên:
2. Thống kê thời gian làm việc (online / bật nhận lead) theo nhân viên theo ngày
Endpoint: GET /apiring/reports/omni/employees/working-time
Tính thời gian nhân viên online và thời gian nhân viên bật nhận lead (omni) trong lúc online, nhóm theo từng ngày. Nguồn dữ liệu: OmniWorkingTime (mỗi phiên online là 1 document với createdAt/endAt, và mảng listPaused ghi các mốc bật/tắt nhận lead).
Auth: header apikey
Query params
Tham số
Bắt buộc
Kiểu
Mô tả
startDate
✅
ISO date string
Mốc bắt đầu (dùng $gte) — lọc theo thời điểm bắt đầu phiên online (createdAt)
endDate
✅
ISO date string
Mốc kết thúc (dùng $lte)
userIds
❌
string, phân tách ,
Lọc theo danh sách _id nhân viên
Ràng buộc: giống API 1 — ngày hợp lệ, tối đa 90 ngày, userIds phải hợp lệ nếu có.
Cách tính
● onlineTime = tổng thời gian từ lúc online (createdAt) đến lúc offline (endAt); nếu phiên chưa đóng thì tính đến hiện tại hoặc hết ngày hôm đó (lấy mốc nào đến trước).
● pausedTime = tổng thời gian tắt nhận lead trong lúc đang online, tính từ các cặp mốc bật/tắt trong listPaused.
● receivingLeadTime = onlineTime - pausedTime (thời gian online và đang bật nhận lead).
● Ngày dùng để gộp (date) lấy theo ngày local của server tại thời điểm createdAt của phiên (đồng bộ với cách tính "hết ngày" ở trên, không convert riêng theo giờ VN).
Response 200
users sắp xếp theo onlineTimeMs giảm dần.
Response lỗi
Status
message
Nguyên nhân
400
ERROR: Org not found
Không tìm thấy org từ apikey
400
ERROR: Filter time is wrong
Thiếu/sai startDate/endDate
400
ERROR: Filter time within 3 months
Khoảng ngày > 90 ngày
400
ERROR: User ids are invalid
userIds có nhưng không hợp lệ
500
ERROR
Lỗi hệ thống
Ví dụ
Ngày 28/08/2026 giờ VN, 1 nhân viên:
Last updated