Skip to content
入门

团队

什么是团队?

团队是多人共享 API Key 与钱包的协作单位。您可以创建团队与他人协作,通过团队里的 Key(团队 Key 或成员 Key)调用 API 时费用都从团队钱包中扣除。

适用场景

  • 多人开发同一项目,共享 API 配额和费用
  • 为销售或合作伙伴提供独立的 API Key,共享公司的团队钱包
  • 工作室或代理商为多个客户管理 API 使用

创建与加入团队

创建团队

  1. 登录控制台,进入「团队」页面
  2. 点击「创建团队」,输入团队名称
  3. 完成创建后,您成为该团队的 Owner

创建限制:每个账户最多创建 3 个 团队。

邀请成员

  1. 在团队详情页,点击「邀请成员」
  2. 输入被邀请者的邮箱和角色(Admin 或 Member)
  3. 邀请有效期为 7 天

被邀请者需要:

  • 使用该邮箱在本平台注册
  • 用该邮箱登录后接受邀请

重要:只有用被邀请邮箱登录的用户才能接受邀请。邀请不能替代注册,被邀请者需自行注册账户。

加入团队

当您收到邀请时:

  1. 登录控制台,进入「待处理邀请」
  2. 查看邀请的团队、邀请人和角色(邀请人邮箱部分隐藏,例如 ow***@example.com)
  3. 点击「接受」或「拒绝」

加入限制:每个账户最多加入 10 个 团队(包括自己创建的);每个账户最多拥有 3 个 团队。

角色与权限

团队有三种角色,权限如下:

功能OwnerAdminMember
查看成员列表✓✓✓
邀请成员✓✓—
移除 Member✓✓—
移除 Admin✓——
改变成员角色✓——
转让 Owner✓——
解散团队✓——
查看团队余额✓✓✓
充值团队钱包✓——
查看充值记录✓✓—
查看全员消费流水✓✓—
查看个人消费✓✓✓(仅自己的)
创建团队 Key✓✓—
创建成员 Key✓✓✓(仅自己的)
管理 Key✓✓✓(仅自己的)

说明:

  • balance 对所有角色可见(Member 可看团队余额数字)
  • 充值、流水、全员用量仅 Owner/Admin 可看
  • Member 只能查看自己的 Key 与用量
  • Admin 只能移除 Member;移除 Admin 仅 Owner 能做;Owner 不可被移除,需先转让
  • 他人的邮箱(成员、邀请、Key 持有人、用量行、订单付款人)由服务端打码后返回,例如 wi***@gmail.com;自己的邮箱完整显示

成员 Key 与团队 Key 的区别

成员 Key

  • 持有人:创建它的成员本人
  • 费用来源:团队钱包(不扣个人余额)
  • 访问权限:仅成员本人使用
  • 退出/被移出:成员退出或被移出团队时,删除成员关系和吊销该成员的成员 Key 在同一个事务里完成,后续调用返回 401

团队 Key

  • 持有人:以 Owner 的名义持有(仅 Owner/Admin 可创建)
  • 费用来源:团队钱包
  • 访问权限:全团队成员共用
  • 退出/转让:成员退出或被移出不影响团队 Key;转让所有权时,团队 Key 随之转给新 Owner

团队钱包与充值

充值方式

只有 Owner 可以为团队充值。充值支持:

  • Stripe:信用卡/借记卡
  • OxaPay:多种支付方式

充值流程

  1. 在团队详情页,点击「充值」
  2. 选择支付方式和金额
  3. 完成支付后,金额自动进入团队钱包
  4. 页面会返回到团队页,显示「充值成功」或「已取消」的提示

重要:

  • 返回页面时,系统会重新拉取后端余额数据,以支付回调为准
  • 如果充值处理较慢,页面会显示「处理中」

充值单的二维码与状态字段

二维码(qrCode)

充值单的 qrCode 字段由支付供应商提供,用于展示支付二维码。客户端应注意:

  • 格式未由本平台规范,可能是 URL、base64 编码或其他格式
  • 不应对格式做任何假设,以供应商文档为准
  • OxaPay 返回空值时为 null;Stripe 订单类型中无此字段

状态字段:status 与 publicStatus

充值单有两个状态字段,用途不同:

字段定义值示例用途
status原始状态字符串(供应商状态和本地处理状态)OxaPay: new, paid, expired 等;本地: creating, creation_failed 等内部记录、调试
publicStatus规范化状态(平台定义)pending、partial、paid、refunded、failed、expired对外 API、用户界面展示

OxaPay 支持的 status 值(供参考,以 src/lib/payments/oxapay/store.ts 的 PROVIDER_STATUSES 为准,并保持此列表同步):

  • 官方小写值:new、waiting、paying、paid、underpaid、refunding、refunded、expired
  • manual_accept:商户在 OxaPay 后台手动接受发票;校验和幂等与 paid 相同,并以本地订单金额入账。沙箱订单、已解散团队的订单不入账;未入账时 publicStatus 仍为 pending
  • 本地值:creating、creation_failed、creation_unknown、creation_void

使用建议:

  • 客户端展示支付进度时应使用 publicStatus(规范化、不变)
  • 轮询 GET /api/me/topup/{stripe|oxapay}/:id 时应关注 publicStatus,不需要解析 status。响应中的 stale 为 false 表示本次轮询成功刷新订单,为 true 表示无法刷新(例如缺少供应商订单标识、状态不匹配或查询出错);它不表示订单已多久未更新。
  • status 作为供应商原始信息保留供技术支持和调试

团队消费

  • 使用团队 Key 或成员 Key 发起的 API 请求,费用 仅从团队钱包扣除
  • 团队消费不影响个人余额、个人用量或个人对账
  • 团队消费 不计入返佣基数
  • 团队钱包余额不足(≤ 0)时,使用团队 Key 或成员 Key 会返回 HTTP 402

移除成员与解散团队

移除成员

  • Owner 可以移除 Admin 和 Member
  • Admin 只能移除 Member
  • Owner 不能被移除
  • 移除成员关系和吊销该成员的 成员 Key 在同一个事务里完成,后续调用返回 401;该成员的 个人 Key 不受影响

自己退出

  • Admin 和 Member 可以主动退出团队
  • Owner 要先把所有权转让给其他成员才能退出,否则返回 owner_must_transfer
  • 退出时,您的成员 Key 在同一个事务里被吊销(之后返回 401),个人 Key 保留

转让所有权

  • 仅 Owner 可以把所有权转让给团队里的另一位成员
  • 转让后原 Owner 变为 Admin,团队 Key 随之转给新 Owner

解散团队

仅 Owner 可以解散团队,条件:

  • 团队余额 ≤ 0(不能有余额遗留)
  • 无未结充值单

解散时(同一个事务):

  • 团队的全部 Key(团队 Key 和成员 Key)被吊销
  • 未处理的邀请被撤销,全部成员关系被移除
  • 团队状态改为 disbanded;团队本身、钱包流水和调用记录(trace)都保留,不会删除

限制与约束

成员上限

  • 每个团队最多 10 个 成员(包括还未接受邀请的邀请对象)

Key 上限

  • 每个团队最多 50 个 Key(团队 Key 和成员 Key 合计,已吊销的不计)

创建与加入上限

  • 每人最多拥有(创建)3 个 团队
  • 每人最多加入 10 个 团队(包括自己创建的)

返佣与领码

  • 团队充值与消费 不进返佣基数
  • 领取邀请码不需要充值(2026-11-09 起),与团队无关

本期不支持功能

以下功能将在后续版本中支持,目前不可用:

  • 成员月度用量上限:暂无
  • 团队租赁:团队 Key 暂不支持用作租赁 Key
  • 余额退回:充值后的团队余额暂不支持回到个人账户

常见问题

Q:如何更改成员角色?

A:进入团队详情 → 成员列表 → 点击成员 → 选择新角色。仅 Owner 有权限。

Q:Member 能否创建 Key?

A:Member 只能创建「成员 Key」(费用从团队钱包扣)。创建「团队 Key」需 Owner/Admin 权限。

Q:如果 Owner 被封禁会怎样?

A:封禁期间,该团队的全部 Key(团队 Key 和成员 Key)调用 API 都返回 403,成员无法使用。

Q:邀请过期后怎么办?

A:邀请有效期为 7 天。过期后 Owner/Admin 需重新发送邀请。

Q:成员退出后费用如何结算?

A:团队消费是按请求时实时扣费的,退出不影响已产生的费用。