POST /apiv2/billing/limits

在 Netts 设定的信用额度内创建、修改、停用和启用您自己的额度限制。通过这些端点无法修改 Netts 设定的额度限制。属于后付费计费的一部分。

端点

端点	功能
POST /apiv2/billing/limits	创建您自己的额度限制
PUT /apiv2/billing/limits/{id}?scope=account	修改其数值
POST /apiv2/billing/limits/{id}/disable?scope=account	停用该限制 — 停止生效，不会删除任何内容
POST /apiv2/billing/limits/{id}/enable?scope=account	重新启用该限制

{id} 是来自额度限制的限制 id。进行修改时必须携带 scope=account。

请求头

请求头	必填	描述
X-API-KEY	是	拥有 limits.write 权限的 API 密钥
X-Real-IP	是	来自密钥白名单中的地址
Idempotency-Key	是	唯一字符串，8–128 个字符，每次变更一个
Content-Type	是	application/json

Idempotency-Key 确保重试的安全性。使用相同的密钥和相同的请求体重复请求（例如在超时后），您将收到原本的响应结果；变更不会被执行两次。使用相同的密钥但请求体不同将被拒绝，并返回 409 idempotency_conflict。

expectedRevision 可防止您覆盖尚未查看到的变更。传入您上次读取的 revision（创建额度限制时为 0）。如果额度限制在此期间发生了变更，请求将被拒绝并返回 409 revision_conflict — 请重新读取额度限制并重试。

创建额度限制

字段	类型	必填	描述
productCode	字符串或 null	否	energy_1h、energy_5m、bandwidth、activation、aml_check；若为您的总额度限制则为 null 或省略
period	字符串	是	outstanding、day、week 或 order
value	字符串	是	金额，采用 Netts 额度限制的币种，不得高于该限额
expectedRevision	整数	是	0

您可以针对每个产品和周期拥有一个属于您自己的额度限制。币种取自 Netts 额度限制 — 没有币种字段。

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

该额度限制将立即应用于下一笔订单。

修改额度限制

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}'

字段	类型	必填	描述
value	字符串	是	新金额，不得高于 Netts 额度限制
expectedRevision	整数	是	该额度限制当前的 revision

响应格式与上述相同，revision 会递增 1。

停用或启用额度限制

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}'

请求体仅包含 expectedRevision。/enable 的使用方式相同。已停用的额度限制仍保留在列表中，其状态为 "enabled": false，并且可以在之后重新启用；您的欠款和扣费不受影响。

禁止的操作

• 修改或停用带有 "origin": "netts" 的额度限制或密钥限制 — 将返回 403 netts_limit_readonly，即使是调低也不允许。
• 设置高于 Netts 额度限制的数值 — 将返回 422 above_account_limit。
• 为同一产品和周期创建第二个额度限制 — 将返回 409 limit_exists；请改为修改现有额度限制。
• 在 Netts 为您的账户设置信用额度之前创建额度限制 — 将返回 409 no_account_limit。
• 启用币种与当前 Netts 额度限制不一致的额度限制 — 将返回 422 unit_mismatch；请先设置新的数值。

错误响应

HTTP	code	含义
400	invalid_request, invalid_amount	字段缺失或格式错误
400	idempotency_key_required, invalid_idempotency_key	缺少 Idempotency-Key，或长度不在 8–128 个字符范围内
401	-1, -2	密钥缺失或无效，或 IP 不在白名单内 — 由 API 网关返回，参见响应格式
403	forbidden	密钥缺少 limits.write 权限
403	postpaid_disabled	后付费计费已暂停：无法修改额度限制
403	netts_limit_readonly	该额度限制由 Netts 设定
404	not_found	您的账户中不存在该额度限制
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	参见上方说明
422	above_account_limit, product_not_postpaid, unit_mismatch	数值高于 Netts 额度限制、未知产品、Netts 额度限制的币种发生变更

所有代码均列于后付费计费中。