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

Bốn endpoint dưới đây giúp bạn đối chiếu số lượt của đơn vị với số liệu phía bạn. Tất cả đều là GET và không trừ lượt.

Endpoint	Dùng để
`GET /balance`	Xem số dư hiện tại theo từng loại sản lượng
`GET /ledger`	Xem từng biến động của ví: được cấp, chia, thu hồi, trừ, hoàn
`GET /transactions`	Xem từng lần gọi xác thực và kết quả
`GET /usage/summary`	Xem tổng số lần gọi theo ngày hoặc tháng

Các ví dụ dùng biến EVERIFY_API_KEY và EVERIFY_BASE_URL (xem Bắt đầu nhanh). Tham số và schema đầy đủ xem Tham chiếu API.

Quy ước chung

Dữ liệu luôn là của đơn vị sở hữu ứng dụng, không gồm chi nhánh hay đơn vị cấp trên.
from, to theo ISO 8601 và đều tính cả mốc biên.
- Có giờ, ví dụ 2026-10-01T00:00:00+07:00, là một thời điểm cụ thể.
- Ngày trần YYYY-MM-DD tính theo giờ Việt Nam. from=2026-10-01 bắt đầu từ 00:00 ngày 1. to=2026-10-31 gồm hết ngày 31.
Khoảng from–to tối đa 31 ngày với /transactions và 366 ngày với /ledger, /usage/summary.
Danh sách trả { items, next_cursor }, mới nhất trước. limit từ 1 đến 100 (mặc định 50). Truyền next_cursor vào cursor để lấy trang kế. next_cursor là null nghĩa là hết dữ liệu.
Tham số sai (sai kiểu, giá trị lạ, from sau to, khoảng quá dài, cursor sai) nhận 400 INVALID_REQUEST.

Số dư: `GET /balance`

Trả một dòng cho mỗi loại sản lượng của đơn vị.

curl -sS "$EVERIFY_BASE_URL/balance" -H "X-API-Key: $EVERIFY_API_KEY"

{
  "request_id": "req_01JBF8...",
  "data": {
    "enterprise_code": "VPCC-DA",
    "balances": [
      {
        "quota_type": "eid_verify",
        "name": "Xác thực eID",
        "total_in": 10000,
        "total_out": 0,
        "used": 5001,
        "reserved": 0,
        "balance": 4999
      }
    ]
  },
  "error": null
}

Trường	Ý nghĩa
`quota_type`, `name`	Mã và tên loại sản lượng
`total_in`	Tổng lượt đã nhận: được VTS cấp, được đơn vị cấp trên chia, thu hồi về từ chi nhánh
`total_out`	Tổng lượt đã đi ra: bị VTS rút, chia cho chi nhánh, bị đơn vị cấp trên thu hồi
`used`	Số lượt đã dùng cho các lần xác thực có kết luận
`reserved`	Số lượt đang tạm giữ cho request chưa xong
`balance`	Số lượt còn dùng được: `total_in − total_out − used − reserved`

Sổ biến động: `GET /ledger`

Mỗi dòng là một bút toán của ví. amount luôn là số dương. Chiều tăng hay giảm do kind quyết định. balance_after là số dư ví ngay sau bút toán.

`kind`	Chiều	Biến động	`counterparty`
`GRANT`	Tăng	VTS cấp sản lượng	`{ "name": "VTS" }`
`REVOKE`	Giảm	VTS rút sản lượng	`{ "name": "VTS" }`
`ALLOCATE_IN`	Tăng	Nhận sản lượng do đơn vị cấp trên chia	Đơn vị cấp trên
`ALLOCATE_OUT`	Giảm	Chia sản lượng cho chi nhánh	Chi nhánh nhận
`RECLAIM_IN`	Tăng	Thu hồi sản lượng từ chi nhánh về	Chi nhánh bị thu hồi
`RECLAIM_OUT`	Giảm	Bị đơn vị cấp trên thu hồi	Đơn vị cấp trên
`DEBIT`	Giảm	Trừ lượt cho một giao dịch	`null`
`REFUND`	Tăng	Hoàn lại lượt đã trừ của một giao dịch, khi VTS điều chỉnh	`null`

Với chia và thu hồi, counterparty là { "enterprise_code", "enterprise_name" } của đơn vị bên kia.
transaction_id (txn_...) chỉ có với DEBIT và REFUND, các loại khác là null.
note là ghi chú khi cấp hoặc rút, có thể là null.
Lượt tạm giữ được nhả lại khi có lỗi không xuất hiện trong sổ cái vì chưa bị trừ.
VTS chỉ cấp cho đơn vị gốc, nên GRANT và REVOKE chỉ xuất hiện ở đơn vị gốc. Chi nhánh thấy ALLOCATE_IN, RECLAIM_OUT và DEBIT.

Tham số:

Tham số	Ý nghĩa
`quota_type`	Mã loại sản lượng, ví dụ `eid_verify`
`kind`	Một hoặc nhiều loại, cách nhau dấu phẩy: `kind=DEBIT,REFUND`
`from`, `to`	Khoảng thời gian, tối đa 366 ngày. Mặc định là 366 ngày gần nhất
`cursor`, `limit`	Phân trang

curl -sS -G "$EVERIFY_BASE_URL/ledger" -H "X-API-Key: $EVERIFY_API_KEY" \
  --data-urlencode "quota_type=eid_verify" \
  --data-urlencode "kind=GRANT,ALLOCATE_IN,RECLAIM_OUT" \
  --data-urlencode "from=2026-01-01" \
  --data-urlencode "to=2026-10-31"

Giao dịch: `GET /transactions`

Mỗi dòng là một lần gọi xác thực: transaction_id, client_ref, product, status, result, charged, id_number_masked, created_at, error_code.

Tham số	Ý nghĩa
`from`, `to`	Khoảng thời gian, tối đa 31 ngày. Mặc định là 31 ngày gần nhất
`status`	`SUCCEEDED` hoặc `FAILED`
`quota_type`	Mã loại sản lượng
`product`	Sản phẩm, hiện có `eid.verify`
`client_ref`	Khớp chính xác mã giao dịch phía bạn
`scope`	`app` (mặc định): chỉ ứng dụng đang gọi. `enterprise`: mọi ứng dụng của đơn vị
`cursor`, `limit`	Phân trang

Khi scope=enterprise, mỗi dòng có thêm app_name và app_key_id (key_id công khai của ứng dụng đã gọi).

curl -sS -G "$EVERIFY_BASE_URL/transactions" -H "X-API-Key: $EVERIFY_API_KEY" \
  --data-urlencode "client_ref=HS-2026-000123"

Tổng hợp: `GET /usage/summary`

Gộp số lần gọi theo ngày hoặc tháng, tính theo giờ Việt Nam.

Tham số	Bắt buộc	Ý nghĩa
`from`, `to`	Có	Khoảng thời gian, tối đa 366 ngày
`group_by`	Không	`day` (mặc định) hoặc `month`
`quota_type`	Không	Mã loại sản lượng. Bỏ trống là mọi loại
`scope`	Không	`enterprise` (mặc định): mọi ứng dụng của đơn vị. `app`: chỉ ứng dụng đang gọi

{
  "request_id": "req_01JBF8...",
  "data": {
    "from": "2026-09-30T17:00:00.000Z",
    "to": "2026-10-31T16:59:59.999Z",
    "group_by": "month",
    "scope": "enterprise",
    "time_zone": "Asia/Ho_Chi_Minh",
    "rows": [
      { "period": "2026-10", "quota_type": "eid_verify", "total": 1250, "charged": 1210, "valid": 1180, "invalid": 30, "failed": 40 }
    ],
    "totals": { "total": 1250, "charged": 1210, "valid": 1180, "invalid": 30, "failed": 40 }
  },
  "error": null
}

Trường	Ý nghĩa
`from`, `to`	Khoảng đã chuẩn hoá, giờ UTC
`period`	`YYYY-MM-DD` hoặc `YYYY-MM`, theo giờ Việt Nam
`total`	Số giao dịch đã kết thúc, kể cả lỗi hoặc bị từ chối. Không tính giao dịch đang xử lý
`charged`	Số lượt đã trừ
`valid`, `invalid`	Số kết luận `VALID`, `INVALID`
`failed`	Số giao dịch lỗi hoặc bị từ chối, không trừ lượt

total = valid + invalid + failed. Chỉ có dòng cho kỳ có giao dịch, sắp theo period rồi quota_type. totals cộng dồn mọi dòng.

Quy trình đối soát cuối tháng

Ví dụ đối soát tháng 10/2026 cho toàn đơn vị. Cần jq để đọc JSON.

1. Lấy tổng của tháng

curl -sS -G "$EVERIFY_BASE_URL/usage/summary" -H "X-API-Key: $EVERIFY_API_KEY" \
  --data-urlencode "from=2026-10-01" \
  --data-urlencode "to=2026-10-31" \
  --data-urlencode "group_by=month" | jq '.data.totals'

2. Xuất toàn bộ giao dịch của tháng ra file

cursor=""
: > transactions-2026-10.jsonl
while :; do
  page=$(curl -sS -G "$EVERIFY_BASE_URL/transactions" -H "X-API-Key: $EVERIFY_API_KEY" \
    --data-urlencode "from=2026-10-01" \
    --data-urlencode "to=2026-10-31" \
    --data-urlencode "scope=enterprise" \
    --data-urlencode "limit=100" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  echo "$page" | jq -c '.data.items[]' >> transactions-2026-10.jsonl
  cursor=$(echo "$page" | jq -r '.data.next_cursor // empty')
  [ -z "$cursor" ] && break
done
wc -l transactions-2026-10.jsonl

3. So khớp

totals.charged ở bước 1 phải bằng tổng charged của các giao dịch ở bước 2:
```
jq -s 'map(.charged) | add' transactions-2026-10.jsonl
```
Đối chiếu từng giao dịch với hệ thống của bạn qua client_ref. Cột app_name cho biết ứng dụng nào đã gọi.
Xem lượt được cấp, chia và thu hồi trong tháng bằng GET /ledger với cùng from, to và kind=GRANT,REVOKE,ALLOCATE_IN,ALLOCATE_OUT,RECLAIM_IN,RECLAIM_OUT.

Nếu số liệu lệch

Gửi cho VTS khoảng thời gian đối soát và các transaction_id hoặc request_id liên quan.

Quy ước chung​

Số dư: GET /balance​

Sổ biến động: GET /ledger​

Giao dịch: GET /transactions​

Tổng hợp: GET /usage/summary​

Quy trình đối soát cuối tháng​