> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econtractid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Đối soát sản lượng

> Tra cứu số lượng hồ sơ hoàn thành, dung lượng và lượt gọi eKYC, eID, OCR, Liveness, chứng thư số để đối soát với hoá đơn

Trang này gồm 2 endpoint chỉ đọc để tổ chức của bạn tự đối soát sản lượng đã sử dụng. Số liệu cùng nguồn với màn hình [Báo cáo sản lượng](https://docs.econtractid.com/user-guide/quan-tri/bao-cao-san-luong.md) trên giao diện, nên cùng một kỳ sẽ cho cùng kết quả.

| # | Endpoint | Mục đích |
| - | - | - |
| 1 | `GET /api/integration/usage/summary` | Tổng hợp cấp / dùng / còn lại theo loại sản lượng |
| 2 | `GET /api/integration/usage/records` | Chi tiết từng giao dịch, mới nhất trước |

## Xác thực và phạm vi

Gửi header `X-API-Key` của **key theo tổ chức**, xem [Xác thực](https://docs.econtractid.com/api-reference/xac-thuc.md). Số liệu thuộc về **tổ chức gốc** (tenant) chứa tổ chức mà key được gắn, gồm toàn bộ đơn vị con.

* Request dùng access token thay cho API Key bị từ chối `403`.
* Key không gắn tổ chức cụ thể (key toàn cục) không dùng được endpoint này.

## Nhãn `quotaCode`

Dùng nhãn thay cho id nội bộ. Mọi loại sản lượng khác không xuất hiện trong kết quả.

| `quotaCode` | Ý nghĩa | `unit` | Cách tính |
| - | - | - | - |
| `FOLDER_COMPLETED` | Hồ sơ hoàn thành | `count` | Mỗi lần quy trình của hồ sơ hoàn thành tính 1. Xoá hồ sơ **không** làm giảm số đã tính; hồ sơ đã xoá vẫn có trong `/records` |
| `FILE_STORAGE` | Dung lượng lưu trữ | `bytes` | Tổng dung lượng các file **đang lưu trong hồ sơ**, tính theo byte. Mỗi file tính phiên bản mới nhất. Upload thì cộng; xoá file hoặc xoá hồ sơ chứa file thì file đó không còn được tính. File không nằm trong hồ sơ nào không được tính |
| `EKYC` | Xác thực eKYC | `count` | Mỗi lượt gọi |
| `EID` | Xác thực eID | `count` | Mỗi lượt gọi |
| `OCR_CARD` | OCR giấy tờ định danh | `count` | Mỗi lượt OCR **thành công** |
| `LIVENESS` | Kiểm tra người thật | `count` | Mỗi lượt gọi |
| `CERTIFICATE` | Cấp chứng thư số | `count` | Mỗi lượt gọi |

> [!NOTE]
>
> Với `EKYC`, `EID`, `LIVENESS`, `CERTIFICATE`, **lượt gọi thất bại vẫn được tính** vì nhà cung cấp vẫn tính phí lượt đó. Riêng `OCR_CARD` chỉ tính lượt thành công: lượt thất bại vẫn xuất hiện trong `/records` với `success: false` nhưng không cộng vào `used`. Dùng `success` để tách lượt thành công và thất bại khi đối soát.

Ngày trong `fromDate` / `toDate` tính theo **giờ Việt Nam**, gồm cả ngày cuối.

Số liệu chỉ tính cho tổ chức gốc còn hoạt động; số của các đơn vị con được cộng vào tổ chức gốc.

***

## 1. Tổng hợp

```http theme={null}
GET /api/integration/usage/summary?fromDate=2026-10-01&toDate=2026-10-31&groupBy=month&quotaType=EKYC
X-API-Key: econtract_a1b2c3d4e5f6...
```

### Tham số

| Tham số | Bắt buộc | Mô tả |
| - | - | - |
| `fromDate` | Có | `YYYY-MM-DD` |
| `toDate` | Có | `YYYY-MM-DD`, không sớm hơn `fromDate`. Khoảng tối đa **366 ngày** |
| `groupBy` | Không | `day`, `month` hoặc `year`. Khi có, mỗi loại trả thêm mảng `series` |
| `quotaType` | Không | Một nhãn `quotaCode`, không phân biệt hoa thường. Bỏ trống → mọi loại |

### Response `200`

```json theme={null}
{
  "period": { "fromDate": "2026-10-01", "toDate": "2026-10-31", "groupBy": "month" },
  "items": [
    {
      "quotaCode": "EKYC",
      "quotaType": 4,
      "unit": "count",
      "used": 30,
      "allocated": 120,
      "remaining": 90,
      "byProvider": [{ "provider": "VNPT", "used": 10 }],
      "byDocumentType": [{ "documentType": 4, "used": 30 }],
      "series": [{ "period": "2026-10", "used": 30 }]
    }
  ]
}
```

| Trường | Mô tả |
| - | - |
| `period.groupBy` | Chỉ có khi request truyền `groupBy` |
| `items[].quotaType` | Id nội bộ, chỉ để tham khảo. Hãy dựa vào `quotaCode` |
| `items[].used` | Số đã dùng trong kỳ, theo `unit`. Với `FILE_STORAGE` là tổng byte của các file đang lưu được upload trong kỳ |
| `items[].allocated` | Tổng hạn mức được cấp còn hiệu lực trong kỳ (gói có ngày bắt đầu / kết thúc giao với kỳ), gồm cả phần có phí và phần miễn phí, theo `unit`. Với `FILE_STORAGE` là **byte** |
| `items[].remaining` | Loại tính theo lượt: `allocated` trừ `used`. `FILE_STORAGE`: `allocated` trừ tổng dung lượng đang lưu tính tới hết `toDate`. Có thể **âm** khi dùng vượt cấp |
| `items[].byProvider` | Số dùng theo nhà cung cấp (nếu loại đó có) |
| `items[].byDocumentType` | Số dùng theo loại tài liệu trong hồ sơ (`documentType`, xem bảng dưới) |
| `items[].series` | Chuỗi theo `groupBy`. `period` có dạng `YYYY-MM-DD`, `YYYY-MM` hoặc `YYYY` |

`items` sắp theo id nội bộ của loại sản lượng tăng dần.

***

## 2. Chi tiết giao dịch

```http theme={null}
GET /api/integration/usage/records?fromDate=2026-10-01&toDate=2026-10-31&quotaType=EKYC&page=1&pageSize=50
X-API-Key: econtract_a1b2c3d4e5f6...
```

### Tham số

| Tham số | Bắt buộc | Mô tả |
| - | - | - |
| `fromDate`, `toDate` | Có | Như trên. Khoảng tối đa **366 ngày** |
| `quotaType` | Không | Một nhãn `quotaCode`. Bỏ trống → mọi loại |
| `documentCode` | Không | Mã hồ sơ, khớp một phần, không phân biệt dấu |
| `page` | Không | Bắt đầu từ 1. Mặc định 1 |
| `pageSize` | Không | Từ 1 đến **500**. Mặc định 20 |

### Response `200`

```json theme={null}
{
  "total": 51,
  "page": 1,
  "pageSize": 50,
  "items": [
    {
      "usedAt": "2026-10-05T01:00:00.000Z",
      "quotaCode": "EKYC",
      "quotaType": 4,
      "unit": "count",
      "action": "USE",
      "amount": 1,
      "provider": "VNPT",
      "documentId": 9,
      "documentCode": "HD-2026-001",
      "documentName": "Hợp đồng dịch vụ — Nguyễn Văn A",
      "documentType": 4,
      "performedBy": "Nguyễn Văn A",
      "success": true
    }
  ]
}
```

| Trường | Mô tả |
| - | - |
| `usedAt` | Thời điểm ghi nhận, UTC (ISO 8601) |
| `action` | `COMPLETE` (hồ sơ hoàn thành), `USE` (lượt gọi dịch vụ), `UPLOAD` (file đang lưu, chỉ với `FILE_STORAGE`) |
| `amount` | Số lượng của giao dịch, theo `unit`. Với `FILE_STORAGE`, mỗi dòng là một file đang lưu trong hồ sơ, upload trong kỳ, `amount` là dung lượng phiên bản mới nhất (byte); tổng `amount` bằng `used` của `/summary` cùng kỳ. `usedAt` là thời điểm upload phiên bản đó |
| `documentId` | Id hồ sơ trong econtractid. Khác với `documentId` bạn tự cấp khi tạo hồ sơ |
| `documentCode`, `documentName` | Mã và tên hồ sơ liên quan. `null` nếu giao dịch không gắn hồ sơ. Hồ sơ đã xoá vẫn trả về (với `FOLDER_COMPLETED`) |
| `documentType` | Loại tài liệu: 1 Tài liệu chính, 2 Tệp đính kèm, 3 Tài liệu xác thực, 4 Tài liệu chứng thực, 5 Tài liệu số hoá, 6 Tài liệu video call, 7 Tài liệu chuyển đổi, 8 Tài liệu ngăn chặn, 9 Giấy tờ định danh, 10 Tài sản, 11 Công chứng giấy, 98 Tài liệu ký trực tiếp, 99 Khác |
| `performedBy` | Người thực hiện |
| `success` | `false` với lượt gọi thất bại. `null` nếu giao dịch không có khái niệm thành công / thất bại |

***

## Lỗi

Cấu trúc lỗi và các lỗi xác thực `401` xem [Mã lỗi](https://docs.econtractid.com/api-reference/ma-loi.md).

| HTTP | Nguyên nhân |
| - | - |
| `400` | Thiếu hoặc sai định dạng `fromDate` / `toDate`; `toDate` sớm hơn `fromDate`; khoảng vượt 366 ngày; `groupBy` ngoài `day`, `month`, `year`; `quotaType` không thuộc bảng nhãn (thông báo liệt kê các nhãn hợp lệ); `page`, `pageSize` ngoài giới hạn |
| `401` | API Key không hợp lệ |
| `403` | Gọi bằng access token thay vì API Key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.