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

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

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

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`

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

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`

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

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

Tổng quan

Xác thực

Endpoints

Webhook

Mã lỗi

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

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

Nhãn `quotaCode`

1. Tổng hợp

Tham số

Response `200`

2. Chi tiết giao dịch

Tham số

Response `200`

Lỗi

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

​Nhãn quotaCode

​1. Tổng hợp

​Tham số

​Response 200

​2. Chi tiết giao dịch

​Tham số

​Response 200

​Lỗi

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

Nhãn `quotaCode`

1. Tổng hợp

Tham số

Response `200`

2. Chi tiết giao dịch

Tham số

Response `200`

Lỗi