跳到正文
Indiana
控制台
开发文档
章节目录 / 积分与用量

积分与用量

查询余额，原子消费，预扣并结算异步任务。

SDK 示例对应当前 API。核对匹配版本与 HTTP 接入方式

API v1更新于

开始前准备

完成身份接入；配置 Feature 的稳定 UUID 和授予额度的 Product。读取需要 credits:read，服务端消费需要 credits:consume。

查询余额

配置当前 credit 费率

产品与计费 → 权益 → credit

配置示意图，使用示例数据；具体操作入口以当前控制台为准。

  1. 报价与执行分开

    quoteBalance 用于只读预估；可信后端 mutateBalance 执行 consume、reserve、confirm、release 或 refund，并保留原幂等键。

完成后检查Feature 保存当前配置，Product 保存后以返回的条款为准；已接受用量保留计价事实，实际消费使用原子余额 API。

app/credits.tsTypeScript
const { holdings } = await grow.readHoldings();const { quote } = await grow.quoteBalance({  operation: "quote", internal_feature_id, quantity: "1", properties: {},});const { ledger } = await grow.readLedger({  type: null, from: null, to: null, after: null, limit: 50,});// 只用于展示。消费必须在可信服务端完成。

浏览器使用当前客户 Token 与 credits:read。数量传十进制字符串；quoteBalance 只用于展示，不替代真正扣量。共享池、费率与来源由当前功能配置和固定套餐条款确定。

原子消费

  • 需要私密服务端 Key 的 credits:consume 权限；customerId 来自可信登录身份映射。
  • 同客户、同操作、同幂等键与同参数重试返回原收据，换参数会冲突；响应丢失不能换键再扣。
  • 拒绝结果也保持幂等。余额补足后要发起新的业务尝试，使用新的键。
server/consume.tsTypeScript
const { receipt } = await indiana.mutateBalance({  customerId: authenticatedIndianaCustomerId,  command: {    operation: "consume", internal_feature_id, quantity: "1", properties: {},    idempotencyKey: `job:${jobId}:consume`,  },});if (!receipt.accepted) throw new Error(receipt.reason ?? "Credits unavailable");

预扣与结算

异步任务先预扣，成功确认实际数量，失败 release。最长预扣 24 小时；确认、释放和超时最多一个终态。补扣不足时确认回滚，预扣仍保持 pending。退款引用原成功交易，使用原价格和来源。

server/reserve.tsTypeScript
const { receipt: hold } = await indiana.mutateBalance({  customerId: authenticatedIndianaCustomerId,  command: {    operation: "reserve", internal_feature_id, quantity: "10", properties: {},    expiresInSeconds: 300, idempotencyKey: `job:${jobId}:reserve`,  },});if (!hold.accepted) throw new Error("Insufficient credits");await indiana.mutateBalance({  customerId: authenticatedIndianaCustomerId,  command: {    operation: "confirm", operationId: hold.id, quantity: "8",    idempotencyKey: `job:${jobId}:confirm`,  },});// 失败时通过 mutateBalance 的 release 命令释放 hold.id，不传 quantity。

对应 HTTP 接口

可以在已完成的 HTTP 接入上调用这些操作。每页参考列出完整请求、响应和凭据要求；有匹配 SDK 时，也可使用本页 SDK 示例。

操作与权限
操作HTTP权限
readHoldingsPOST /api/v1/customer-holdingsentitlements:read
quoteBalancePOST /api/v1/balances/quotecredits:read
mutateBalancePOST /api/v1/balances/executecredits:consume
readLedgerPOST /api/v1/customer-ledgercredits:read

操作与权限

  • readHoldings

    HTTP
    POST /api/v1/customer-holdings
    权限
    entitlements:read

  • quoteBalance

    HTTP
    POST /api/v1/balances/quote
    权限
    credits:read

  • mutateBalance

    HTTP
    POST /api/v1/balances/execute
    权限
    credits:consume

  • readLedger

    HTTP
    POST /api/v1/customer-ledger
    权限
    credits:read

相关:readHoldings·quoteBalance·mutateBalance·readLedger

完成后检查

预期结果

用真实收据核对 consume；异步工作用 reserve → confirm / release。重复请求不重复扣量，响应丢失保留原幂等键。