HTTP API 概览

如果你使用非 TypeScript 语言，或者需要直接控制 HTTP 请求细节，可以直接接入柚卡 HTTP API。

如果你使用 TypeScript，通常优先看 SDK 文档，因为它已经封装了鉴权、签名和常用调用方式。

两类 API 的区别

接口面	谁来调用	鉴权方式	能操作谁	典型动作
服务端 API（Private API）	你自己的服务端	Authorization: Bearer <PRIVATE_API_KEY>	项目内任意客户	建客户、开订阅、扣量、代客户兑换卡密
客户端 API（Public Client API）	浏览器、移动端、桌面客户端等公开环境	X-Yuzuca-Key，登录后再加 Authorization: Bearer <ACCESS_TOKEN>	当前登录客户本人	登录、查询自己的订阅、检查自己的权限、为自己兑换卡密

什么时候用哪一类

• 需要创建客户、修改订阅、调整用量、为任意客户兑换卡密：使用 服务端 API（Private API）
• 需要客户登录、查询自己的订阅和授权、为自己兑换卡密：使用 客户端 API（Public Client API）

建议阅读顺序

1. 响应与错误
2. 服务端 API（Private API） 或 客户端 API（Public Client API）
3. 对应端点文档
4. 安全

Scalar API 参考

• Private API 参考：https://yuzuca.sscloud.site/api/private/v1/docs
• Private OpenAPI：https://yuzuca.sscloud.site/api/private/v1/openapi.json
• Public API 参考：https://yuzuca.sscloud.site/api/public/v1/docs
• Public OpenAPI：https://yuzuca.sscloud.site/api/public/v1/openapi.json

开发环境默认对应：

• http://localhost:3000/api/private/v1/docs
• http://localhost:3000/api/private/v1/openapi.json
• http://localhost:3000/api/public/v1/docs
• http://localhost:3000/api/public/v1/openapi.json