POST /apiv2/billing/limits

Tạo, thay đổi, tắt và bật các hạn mức của chính bạn bên trong hạn mức tín dụng do Netts thiết lập. Các hạn mức do Netts thiết lập không thể thay đổi bằng các endpoint này. Một phần của thanh toán trả sau.

Endpoint

Endpoint	Chức năng
POST /apiv2/billing/limits	tạo hạn mức của chính bạn
PUT /apiv2/billing/limits/{id}?scope=account	thay đổi giá trị của nó
POST /apiv2/billing/limits/{id}/disable?scope=account	tắt nó — hạn mức ngừng áp dụng, không có gì bị xóa
POST /apiv2/billing/limits/{id}/enable?scope=account	bật lại nó

{id} là id của hạn mức từ limits. scope=account là bắt buộc đối với các thay đổi.

Tiêu đề yêu cầu

Tiêu đề	Bắt buộc	Mô tả
X-API-KEY	có	Khóa API với quyền limits.write
X-Real-IP	có	Một địa chỉ từ danh sách trắng của khóa
Idempotency-Key	có	một chuỗi duy nhất, 8–128 ký tự, một chuỗi cho mỗi thay đổi
Content-Type	có	application/json

Idempotency-Key giúp việc thử lại an toàn. Lặp lại một yêu cầu với cùng một khóa và cùng một nội dung — ví dụ sau khi hết thời gian chờ (timeout) — và bạn sẽ nhận lại phản hồi gốc; thay đổi không bị thực hiện hai lần. Cùng một khóa với nội dung khác sẽ bị từ chối với lỗi 409 idempotency_conflict.

expectedRevision bảo vệ bạn khỏi việc ghi đè lên thay đổi mà bạn chưa thấy. Gửi revision bạn đã đọc lần gần nhất (0 khi bạn tạo hạn mức). Nếu hạn mức đã thay đổi trong khoảng thời gian đó, yêu cầu sẽ bị từ chối với 409 revision_conflict — hãy đọc lại limits và thử lại.

Tạo một hạn mức

Trường	Loại	Bắt buộc	Mô tả
productCode	chuỗi hoặc null	không	energy_1h, energy_5m, bandwidth, activation, aml_check; null hoặc bỏ qua cho hạn mức tổng thể của bạn
period	chuỗi	có	outstanding, day, week hoặc order
value	chuỗi	có	số tiền, theo loại tiền tệ của hạn mức Netts, không được cao hơn hạn mức đó
expectedRevision	số nguyên	có	0

Bạn có thể có một hạn mức của riêng mình cho mỗi sản phẩm và chu kỳ. Loại tiền tệ được lấy từ hạn mức của Netts — không có trường tiền tệ.

curl -s -X POST 'https://netts.io/apiv2/billing/limits' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-day' \
  -H 'Content-Type: application/json' \
  -d '{"productCode": "energy_5m", "period": "day", "value": "200", "expectedRevision": 0}'

{
  "success": true,
  "data": {
    "id": 5,
    "scope": "account",
    "origin": "client",
    "productCode": "energy_5m",
    "period": "day",
    "enabled": true,
    "limit": { "unit": "USD", "value": "200.000000" },
    "equivalent": { "unit": "TRX", "value": "604.514867" },
    "revision": 1,
    "fx": { "usdPerTrx": "0.33084276", "at": "2026-10-19T20:24:23.449930+00:00" },
    "fxStatus": "ok"
  },
  "timestamp": "2026-10-19T20:30:02+00:00"
}

Hạn mức được áp dụng ngay lập tức cho đơn hàng tiếp theo.

Thay đổi một hạn mức

curl -s -X PUT 'https://netts.io/apiv2/billing/limits/5?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-300' \
  -H 'Content-Type: application/json' \
  -d '{"value": "300", "expectedRevision": 1}'

Trường	Loại	Bắt buộc	Mô tả
value	chuỗi	có	số tiền mới, không được cao hơn hạn mức của Netts
expectedRevision	số nguyên	có	revision hiện tại của hạn mức

Phản hồi có cùng định dạng như trên, với revision được tăng thêm một.

Bật hoặc tắt một hạn mức

curl -s -X POST 'https://netts.io/apiv2/billing/limits/5/disable?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-off' \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision": 2}'

Nội dung yêu cầu chỉ có expectedRevision. /enable hoạt động theo cách tương tự. Một hạn mức bị tắt vẫn nằm trong danh sách với "enabled": false và có thể được bật lại sau; dư nợ và các khoản phí của bạn không bị ảnh hưởng.

Những điều bạn không thể làm

• Thay đổi hoặc tắt hạn mức có "origin": "netts" hoặc hạn mức của khóa — 403 netts_limit_readonly, ngay cả khi muốn giảm hạn mức.
• Thiết lập giá trị cao hơn hạn mức của Netts — 422 above_account_limit.
• Tạo hạn mức thứ hai cho cùng một sản phẩm và chu kỳ — 409 limit_exists; hãy thay đổi hạn mức hiện có để thay thế.
• Tạo hạn mức trước khi Netts thiết lập hạn mức tín dụng cho tài khoản của bạn — 409 no_account_limit.
• Bật hạn mức có loại tiền tệ khác với hạn mức Netts hiện tại — 422 unit_mismatch; hãy đặt giá trị mới trước.

Lỗi

HTTP	code	Ý nghĩa
400	invalid_request, invalid_amount	thiếu một trường hoặc trường có định dạng sai
400	idempotency_key_required, invalid_idempotency_key	không có Idempotency-Key, hoặc không đủ 8–128 ký tự
401	-1, -2	khóa bị thiếu hoặc không hợp lệ, hoặc IP không nằm trong danh sách trắng — được trả về bởi cổng API, xem định dạng phản hồi
403	forbidden	khóa không có quyền limits.write
403	postpaid_disabled	thanh toán trả sau đang tạm dừng: không thể thay đổi hạn mức
403	netts_limit_readonly	hạn mức được thiết lập bởi Netts
404	not_found	không có hạn mức như vậy trên tài khoản của bạn
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	xem ở trên
422	above_account_limit, product_not_postpaid, unit_mismatch	giá trị vượt quá hạn mức của Netts, sản phẩm không xác định, loại tiền tệ của hạn mức Netts đã thay đổi

Tất cả các mã được liệt kê trong thanh toán trả sau.