API 概览
API 是基于 HTTPS 的 JSON 接口，地址为 https://api.kasskeep.com。所有路径都以 /v1 开头；v1 内的变更只增不改。
本参考依据服务的路由定义编写。OpenAPI 规范规划中。
| 分组 | 调用方 | 认证 |
|---|---|---|
| 客户端 API | 你的 App 或网页 | X-Kasskeep-Key: pk_... |
| 服务端 API | 你的后端 | Authorization: Bearer sk_... |
| 入站回调 | 商店和广告网络 | 路径中的 app id 加上渠道自己的签名 |
| 管理 API | 你本人、CLI、自动化脚本 | Authorization: Bearer kks_...（会话）或 kkp_...（个人访问 token） |
错误使用 HTTP 状态码和如下响应体：
{ "error": { "code": "invalid_public_key", "message": "invalid_public_key" } }code 是稳定的；message 给人看，可能会变。
| 状态码 | 常见错误码 |
|---|---|
| 400 | invalid_json、invalid_request（message 会列出每个不合法的字段）、invalid_app_user_id、invalid_environment、invalid_cursor |
| 401 | invalid_public_key、invalid_secret_key、invalid_admin_token、invalid_credentials |
| 403 | tenant_suspended、forbidden、test_store_disabled、test_ads_disabled |
| 404 | not_found、app_not_found、tenant_not_found |
| 409 | 冲突，比如 already_subscribed、external_id_in_use、ad_unit_id_in_use |
| 422 | 缺少配置，比如 android_not_configured、stripe_not_configured |
| 429 | rate_limited |
| 502 | 上游商店 API 暂不可用；可以放心重试 |
客户端 API 和服务端 API 按租户用令牌桶限流，超限返回 429 rate_limited。商店的入站回调从不限流，所以不会丢失任何通知。
同一笔商店交易提交两次，只记录一次，并返回相同的客户状态。恢复购买同样是幂等的。入站回调按各渠道自己的 id 去重。
浏览器只有在 origin 位于 App 的 cors_origins 中时，才能直接调用 Kasskeep（网页结账、在网页里使用测试商店、查询客户）。该列表默认为空。
npx @kasskeep/cli apps update --id app_xxx --cors-origins "https://game.example.com,*.example.com"- 完整的 origin，比如
https://game.example.com（非默认端口要带上端口）。 *.example.com匹配任意层级的https://子域名，但不匹配example.com本身、http://或带端口的 origin。http://localhost:*和http://127.0.0.1:*只在 App 处于非正式模式时允许：apple_environment为sandbox，或开启了测试商店或测试广告。
只有以下使用公钥的接口会发送 CORS 头：POST /v1/receipts、POST /v1/checkout、GET /v1/customers/:id、POST /v1/customers/:id/restore、POST /v1/test-store/purchases、GET /v1/test-store/products、GET /v1/customers/:id/ad-rewards、POST /v1/ads/test/rewards。
响应会原样回显具体的 origin 并带 Vary: Origin，从不设置 Access-Control-Allow-Credentials。预检请求不带密钥，所以只要有任何一个 App 列出了该 origin 就会通过；随后真正的请求再按对应 App 自己的列表检查。密钥校验失败时不返回 CORS 头，在浏览器里会表现为 CORS 错误，所以请先检查密钥。
GET /health 返回 {"ok": true}。