系统边界与接入方式

柚卡负责什么

柚卡提供以下能力：

• API Key 鉴权
• 项目级数据隔离
• 客户与订阅管理
• 功能权限判断
• 计量额度管理
• 卡密兑换与套餐激活
• 会话令牌与请求签名

你的系统通常仍负责什么

• 业务用户体系
• 业务数据与柚卡客户的绑定关系
• 业务动作触发时机
• 密钥保管与轮换
• 失败补偿与重试策略

为什么会有两类接入面

柚卡把接口分成两类，核心原因是权限边界不同：

• 服务端 API（Private API）：给你自己的服务端使用，可以管理项目内任意客户
• 客户端 API（Public Client API）：给浏览器、移动端、桌面端等公开环境使用，只允许当前登录客户操作自己的数据

该怎么选

开始实际接入时，可以按下面的规则判断：

需求	推荐方案
管理任意客户、订阅、额度、卡密	服务端 API（Private API）或 YuzucaPrivateClient
让客户自己登录并读取自己的资料、订阅、额度、卡密	客户端 API（Public Client API）或 YuzucaPublicClient
TypeScript 项目接入	默认优先 SDK
其他语言接入或需要精确控制 HTTP 细节	直接使用 HTTP API

典型调用链路

• 在业务前校验客户是否具备功能权限
• 在业务完成后记录或扣减用量
• 让客户通过卡密开通或延长订阅
• 在客户端查询自己的订阅、额度和卡密记录

具体接口请查看 HTTP API 文档 或 SDK 文档。