合作伙伴 API

面向合作伙伴的服务器间 API：签发密钥，读取店铺配置和地区，创建客户，发放套餐，以及通过您自己的网站或 Telegram 机器人管理订阅链接。

合作伙伴 API 让您可以在 CreateYourVPN 之上构建自己的网站、自己的控制台或 Telegram 机器人。

API 涵盖客户、订阅、套餐和店铺配置。服务器、节点、面板和 SSH 凭据等基础设施不在公开契约的范围内。

仅限服务器之间调用。 请把 API 密钥存放在您的服务器上，不要放进前端代码。带有浏览器请求头的请求会被拒绝，并返回 403 browser_forbidden。

获取密钥

在控制面板中打开账户菜单 → "API"，切换到"密钥"标签页。

为密钥命名（Telegram 机器人、落地页），并只选择它需要的权限。

点击"签发密钥"并复制完整的值。服务只保存密钥的哈希，因此 secret 只显示一次。

每个合作伙伴最多可以有 5 个有效密钥。要轮换密钥，请先签发新密钥，更新集成，再吊销旧密钥。

以 bearer 令牌的形式发送密钥：

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

如果客户端的 Authorization 已被代理占用，也可以使用 X-API-Key: cyv_live_…。

密钥的格式为 cyv_live_<key_id>_<secret>。前半部分（key_id）是公开的：它显示在控制面板中，可以放心地告诉客服。后半部分是 secret。

只读取店铺数据的集成，有 config:read 就够了。只有当集成需要相应的客户操作时，才添加 users:read 或 users:write。

完整、可直接运行的契约位于公开 Postman 集合中。其中包含所有端点、权限、参数、请求体、响应示例和稳定的错误代码。该集合由后端契约生成，是请求和响应结构的最新依据。

浏览所有端点，并将集合复制到您的工作区。

限额按每个密钥单独计算，与请求的 IP 地址无关。

GET /users 之所以有单独的限额，是因为每次请求都会加载完整的客户列表。日常查询请使用 GET /users/{id} 或按 externalId 搜索。

推荐的访问方式。 保存创建客户时返回的 CreateYourVPN 客户 ID，之后用 GET /users/{id} 查询。您可以通过 externalId 把它与自己的标识符关联起来。

有三种操作需要 Idempotency-Key 请求头：发放套餐、重置订阅链接和删除客户。

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

在 24 小时内用同一个键重复请求，会返回已保存的响应，而不会再次执行操作。这样，集成在超时后重试时就不会产生重复的更改。

为每个业务事件（例如一笔付款或一次操作）创建一个键，并在该事件的所有重试中复用它。

如果第一次尝试仍在执行，或者其结果暂时未知，API 会返回 409 conflict，而不会再次执行操作。在决定是否重试之前，请先检查客户的当前状态。

请求和响应的结构请以上方的公开 Postman 集合为准。