> For the complete documentation index, see [llms.txt](https://docs.antbuddy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.antbuddy.com/huong-dan-tich-hop-api-team-technical-api-integration-guide-technical-team/antcrm/21.-api-get-thong-ke-so-cuoc-goi-and-thoi-gian-lam-viec-cua-nhan-vien.md).

# 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

```json
{
  "success": true,
  "total": { "inbound": 120, "outbound": 340, "calls": 460 },
  "totalByDate": [
    { "date": "2026-08-27", "dateDisplay": "27/08/2026", "inbound": 10, "outbound": 25, "total": 35 }
  ],
  "users": [
    {
      "user": {
        "_id": "664342b15cb0c6611b8250e8",
        "firstname": "Văn",
        "lastname": "Nguyễn",
        "email": "user@example.com",
        "avatar": "",
        "displayName": "Văn Nguyễn"
      },
      "totalInbound": 15,
      "totalOutbound": 30,
      "totalCalls": 45,
      "byDate": [
        { "date": "2026-08-27", "dateDisplay": "27/08/2026", "inbound": 3, "outbound": 5, "total": 8 }
      ]
    }
  ]
}
```

*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:*

```json
curl -G 'http://localhost:3002/apiring/reports/calls/by-user-daily' \
  -H 'apikey: YOUR_API_KEY' \
  --data-urlencode 'dateStart=2026-08-27T17:00:00.000Z' \
  --data-urlencode 'dateEnd=2026-08-28T16:59:59.999Z' \
  --data-urlencode 'userIds=664342b15cb0c6611b8250e8'
```

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

```json
{
  "success": true,
  "total": {
    "sessionCount": 42,
    "onlineTimeMs": 29520000,
    "onlineTime": "8h 12m",
    "receivingLeadTimeMs": 27600000,
    "receivingLeadTime": "7h 40m",
    "pausedTimeMs": 1920000,
    "pausedTime": "32m"
  },
  "totalByDate": [
    {
      "date": "2026-08-27",
      "dateDisplay": "27/08/2026",
      "sessionCount": 5,
      "onlineTimeMs": 14400000, "onlineTime": "4h",
      "receivingLeadTimeMs": 13500000, "receivingLeadTime": "3h 45m",
      "pausedTimeMs": 900000, "pausedTime": "15m"
    }
  ],
  "users": [
    {
      "user": {
        "_id": "664342b15cb0c6611b8250e8",
        "firstname": "Văn", "lastname": "Nguyễn",
        "email": "user@example.com", "avatar": "",
        "displayName": "Văn Nguyễn"
      },
      "sessionCount": 3,
      "onlin 
```

*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:*

```json
curl -G 'http://localhost:3002/apiring/reports/omni/employees/working-time' \
  -H 'apikey: YOUR_API_KEY' \
  --data-urlencode 'startDate=2026-08-27T17:00:00.000Z' \
  --data-urlencode 'endDate=2026-08-28T16:59:59.999Z' \
  --data-urlencode 'userIds=664342b15cb0c6611b8250e8' 
```