入门
团队
什么是团队?
团队是多人共享 API Key 与钱包的协作单位。您可以创建团队与他人协作,通过团队里的 Key(团队 Key 或成员 Key)调用 API 时费用都从团队钱包中扣除。
适用场景
- 多人开发同一项目,共享 API 配额和费用
- 为销售或合作伙伴提供独立的 API Key,共享公司的团队钱包
- 工作室或代理商为多个客户管理 API 使用
创建与加入团队
创建团队
- 登录控制台,进入「团队」页面
- 点击「创建团队」,输入团队名称
- 完成创建后,您成为该团队的 Owner
创建限制:每个账户最多创建 3 个 团队。
邀请成员
- 在团队详情页,点击「邀请成员」
- 输入被邀请者的邮箱和角色(Admin 或 Member)
- 邀请有效期为 7 天
被邀请者需要:
- 使用该邮箱在本平台注册
- 用该邮箱登录后接受邀请
重要:只有用被邀请邮箱登录的用户才能接受邀请。邀请不能替代注册,被邀请者需自行注册账户。
加入团队
当您收到邀请时:
- 登录控制台,进入「待处理邀请」
- 查看邀请的团队、邀请人和角色(邀请人邮箱部分隐藏,例如
ow***@example.com) - 点击「接受」或「拒绝」
加入限制:每个账户最多加入 10 个 团队(包括自己创建的);每个账户最多拥有 3 个 团队。
角色与权限
团队有三种角色,权限如下:
| 功能 | Owner | Admin | Member |
|---|---|---|---|
| 查看成员列表 | ✓ | ✓ | ✓ |
| 邀请成员 | ✓ | ✓ | — |
| 移除 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:多种支付方式
充值流程
- 在团队详情页,点击「充值」
- 选择支付方式和金额
- 完成支付后,金额自动进入团队钱包
- 页面会返回到团队页,显示「充值成功」或「已取消」的提示
重要:
- 返回页面时,系统会重新拉取后端余额数据,以支付回调为准
- 如果充值处理较慢,页面会显示「处理中」
充值单的二维码与状态字段
二维码(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:团队消费是按请求时实时扣费的,退出不影响已产生的费用。