跳转到主要内容
上报自定义计费事件,用于 App 的按次(PER_USE)计费场景。每次事件上报会根据 Meter 配置从授权用户的积分中扣除相应金额。

认证

此端点仅支持 OAuth Bearer Token。API Key 认证会返回 401 错误。自定义计费事件从用户账户扣除积分,必须通过 OAuth 确保用户知情同意。

请求体

event
string
必填
事件名称,必须与 App 中配置的 Meter 事件名完全匹配。最大 100 个字符。
idempotency_key
string
必填
幂等键,用于防止重复扣费。相同的 idempotency_key 不会被重复计费。最大 128 个字符。
metadata
object
附加元数据,键值对形式。用于记录额外的业务信息,不影响计费。

请求示例

响应

正常扣费

幂等重放

当同一个 idempotency_key 被重复提交时,不会重复扣费:
idempotent_replay: true 表示这是一次幂等重放,积分未被重复扣除。

幂等性保障

始终使用有意义的幂等键。推荐格式:{业务实体}_{业务ID}_{操作},例如 order_12345_gen_1
  • 防止网络重试导致的重复扣费 — 客户端超时重试时,相同的幂等键保证只扣一次
  • 防止业务逻辑重复调用 — 同一个业务操作多次调用只会扣一次
  • 幂等窗口 — 同一 (app_uuid, idempotency_key) 组合永久有效

工作原理

  1. 你的 App 通过 OAuth 获取用户授权
  2. 用户使用付费功能时,调用 Events API 上报事件
  3. 袋袋根据 App 配置的 Meter 查找对应的积分价格
  4. 从授权用户的积分中扣除对应金额
  5. 返回扣费结果和剩余余额

每日消费上限

平台为每个用户在每个 App 上设置了每日消费上限。达到上限时后续事件上报会被拒绝(HTTP 429)。具体上限值以产品内实时显示为准。

错误码

下一步

计量器配置

查询 App 的 Meter 配置

构建袋袋 App

完整的 App 开发流程