柚卡开发者文档
柚卡是一套面向第三方应用的授权、订阅、额度与卡密平台。
它把原本散落在业务系统里的这些能力统一收口：
- 客户与订阅管理
- 功能权限判断
- 按量额度控制
- 卡密兑换与激活
- API Key 鉴权
- 客户端登录态管理
你的业务系统不需要再自己维护一整套授权中心，只需要在关键节点调用柚卡提供的标准接口。
这套文档适合谁
- 正在把柚卡接入现有产品的工程师
- 需要梳理项目、客户、套餐、订阅关系的开发者
- 需要让 LLM 或 AI 编码工具直接生成接入代码的人
先建立三个认知
- 柚卡不是业务用户中心。你的系统仍负责业务用户、业务数据和业务流程，柚卡负责授权、套餐、额度、卡密和登录令牌。
- 柚卡同时提供服务端高权限接口和客户端自助接口，两者的区别首先是权限边界，其次才是运行环境。
- 接入时最重要的稳定契约是客户标识对象、
feature.slug和plan.slug，而不是展示名称。
推荐阅读顺序
最常见的接入动作
- 在业务执行前判断客户是否拥有某个功能
- 在业务成功后扣减某个功能额度
- 让客户查询自己的订阅、授权和卡密记录
- 让客户通过卡密开通或延长订阅
开始接入时，怎么选接口
当你准备实际写接入代码时，只需要再补一个判断：这次调用应该由谁发起。
| 场景 | 推荐接入面 |
|---|---|
| 代码运行在你自己的服务端，需要管理任意客户、订阅、额度或卡密 | Private API Scalar 参考 或 YuzucaPrivateClient |
| 代码运行在浏览器、移动端、桌面客户端等公开环境，只允许当前登录客户操作自己的数据 | Public API Scalar 参考 或 YuzucaPublicClient |
如果你在 TypeScript 项目中接入，通常优先使用 SDK 文档；如果你使用其他语言，优先查看 HTTP API 文档。