开放 API 接入文档 - 雨云折扣站

概览

产品代码（product）：rcs（云服务器）、rgpu（显卡云）、rbm（裸金属）、rgs（游戏云）、ros（对象存储）。
实例 ID（路径中的 :id、实例列表返回的 id、下单返回的 instance_id）统一为平台资源 ID（平台资源表主键），底层实例 ID 由平台统一维护映射，调用方无需关心。
除少数纯本地查询接口外，所有 /instances/:id/... 接口都必须带 ?product=rcs|rgpu|rbm|rgs|ros；类型不符或资源不属于本商户统一返回 404 instance_not_found（不区分原因，防止探测）。

1. 鉴权（HMAC-SHA256 签名）

API 密钥（Access Key / Secret Key）由您在账号内的「开放平台」页面自助创建（需先由平台客服为账号开通 API 接入权限），可配置 IP 白名单、随时停用或删除。Secret Key 仅在创建时展示一次，遗失后删除旧密钥重新创建即可。

1.1 请求头

头	说明
`X-Access-Key`	平台签发的 Access Key（`ak_` 开头）
`X-Timestamp`	当前 Unix 秒，与服务端偏差不得超过 300 秒
`X-Nonce`	每次请求唯一的随机串（建议 UUID），10 分钟内不可重复（防重放）
`X-Signature`	按下方算法计算的 HMAC-SHA256（十六进制小写）

1.2 签名算法

待签名串为 5 行，以 \n 连接：

<HTTP方法>
<请求路径，含 query，如 /api/open/v1/instances/123?product=rcs>
<X-Timestamp>
<X-Nonce>
<sha256(原始请求体) 的十六进制小写>

GET / DELETE 无请求体时，body 视为空字节串，其 SHA256 为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
query 必须参与签名，query 拼接顺序要与实际请求 URL 完全一致，建议参数固定按字母序。
签名密钥为 Secret Key 原文，算法 HMAC-SHA256，输出十六进制小写。

1.3 curl 示例（GET）

AK="ak_xxx"; SK="sk_xxx"
TS=$(date +%s); NONCE=$(uuidgen)
PQ="/api/open/v1/balance"
HASH="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
SIG=$(printf "GET\n%s\n%s\n%s\n%s" "$PQ" "$TS" "$NONCE" "$HASH" \
      | openssl dgst -sha256 -hmac "$SK" | awk '{print $2}')

curl "https://<域名>${PQ}" \
  -H "X-Access-Key: $AK" -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" -H "X-Signature: $SIG"

POST 时把末行哈希换成 printf '%s' "$BODY" | sha256sum 的结果，并加头 Content-Type: application/json。

1.4 鉴权错误

HTTP	error_code	说明
401	`missing_auth_headers`	四个鉴权头缺一不可
401	`invalid_key`	Key 不存在
401	`timestamp_expired`	时间戳无效或偏差超 ±5 分钟
401	`invalid_signature`	签名不匹配（检查 path/query/body 是否与签名一致）
401	`replay_detected`	Nonce 已被使用
403	`key_disabled`	Key 已停用
403	`ip_forbidden`	来源 IP 不在该 Key 的白名单内
403	`access_revoked` / `account_disabled`	账号 API 接入权限被关闭，或账号已被停用

2. 限流（两级）

级别	阈值	触发响应
商户自身接口	每把 Access Key 5 次/秒（所有接口共享）	429 `rate_limited`，响应头 `Retry-After: 1`
实时操作类接口	全局所有商户共享 1 次/秒（目录/报价/下单/实例实时管控等）	429 `rate_limited`，响应头 `Retry-After: 1`

遇到 429 请至少等待 Retry-After 秒后重试，建议指数退避。
纯本地查询接口（实例列表、本地订单、余额、余额流水等）只受第一级限制；实时操作类接口两级都生效。

3. 幂等（资金类操作必做）

所有会扣款/开通的 POST 接口，请求体必须包含 client_order_id：

字符串，1-64 位，由商户自行生成（建议 业务前缀+订单号/UUID）。
同一把 Access Key 下唯一；以整个原始请求体的 SHA256 校验参数一致性。
同号 + 同请求体重复请求：直接返回首次结果（HTTP 200，响应体一致），不会重复扣款。
同号但请求体不同：409 idempotency_conflict。
首次请求仍在处理中：409 request_processing，响应头 Retry-After: 2，稍后重试。
首次请求失败：返回首次的错误码与信息（不重复下单）。

适用接口：POST /instances（新购）、/renew、/upgrade、/ips、/traffic、/disks/expand、/disks。/release 不扣款，无需幂等号。

4. 响应信封与错误码

成功：

{ "code": 200, "message": "ok", "error_code": "", "data": { } }

失败：

{ "code": 400, "message": "中文错误描述（可直接展示给运维）", "error_code": "invalid_params", "data": null }

error_code	典型场景
`invalid_request` / `invalid_params`	JSON 非法或业务参数不合法
`invalid_product`	product 不在 rcs/rgpu/rbm/rgs/ros
`unsupported_product_action`	该产品不支持此动作（见能力矩阵）
`instance_not_found` / `bucket_not_found`	资源不存在、不属于本商户或产品类型不符
`missing_price`	资金接口未先报价 / 未回传 `price`
`insufficient_balance`	余额不足（先充值）
`idempotency_conflict` / `request_processing`	幂等冲突 / 处理中
`service_error`	平台底层服务返回错误，HTTP 502，message 为可直接展示的中文提示
`rate_limited`	触发两级限流中的任意一级（见第 2 节）
`purchase_failed` / `renew_failed` / `change_failed`	扣款成功但平台执行失败，款项已自动退回余额

所有资金接口均为“先扣款 → 平台执行 → 失败自动退款”，不会出现扣了钱没开通的情况；可通过订单接口核查。

5. 接口清单

所有路径均相对于页面顶部的 Base URL。实时表示实时操作类接口（实时读写实例状态，额外受全局 1/s 限制）。

5.1 账号与资金

方法	路径	说明
GET	`/ping`	连通性/身份校验，返回 `merchant_name/user_id/balance/server_time`
GET	`/balance`	当前余额（元）
GET	`/finance/transactions`	余额流水，分页 `page/page_size`

余额充值（支付宝网页支付）请在平台网站控制台完成，开放 API 不提供代充接口；捕获 insufficient_balance 时引导商户前往网页端充值。

5.2 目录（公开数据）实时

方法	路径	参数
GET	`/catalog/plans`	`product`（必）；返回平台在售套餐（实时数据）
GET	`/catalog/zones`	`product,region,machine`（均必），可用区/节点
GET	`/catalog/os-templates`	`product`（必，ros 不支持）

5.3 实例

方法	路径	说明
POST	`/instances` 实时	新购开通（幂等，见 5.4）
GET	`/instances`	本地实例列表：`product/status/client_ref/page/page_size`
GET	`/instances/:id?product=`	本地快照详情（含 `client_ref` 商户自定义引用号）
GET	`/instances/:id/live?product=` 实时	实时详情（电源状态、IP、硬盘、备份、NAT、套餐等）
POST	`/instances/:id/release?product=` 实时	退订释放（query 必须 `confirm=true`）；已释放返 409

5.4 新购与资金变配（统一“先报价、后下单”）

所有资金下单接口必须先调对应 .../quote 报价，把返回的 price 原样放入下单请求体。服务端以下单瞬间重新算出的价格为准做 ±0.1 元校验，price 不是信任输入。变配/加购类允许 price=0（0 元单不扣款、业务照常执行），仅负数会被拒绝；续费与新购价格恒大于 0。

报价响应统一为：

{ "code": 200, "data": { "instance_id": 123, "product": "rcs",
    "list_price": 50.0, "price": 45.0, "currency": "CNY" } }

5.4.1 新购

报价 POST /quotes：

{ "product": "rcs", "params": { "plan_id": 12, "duration": 1,
    "os_id": 34, "node_uuid": "...", "zone": "...", "displayed_amount": 0 } }

下单 POST /instances：

{ "product": "rcs", "client_order_id": "po-xxx",
  "client_ref": "your-biz-ref-001",
  "params": { "plan_id": 12, "duration": 1, "os_id": 34,
              "node_uuid": "...", "zone": "...",
              "with_eip_num": 1, "add_disk_size": 0, "disk_type": "cloud-ssd",
              "tag": "", "app_vars": [], "displayed_amount": 45.0 } }

产品	核心字段
rcs / rgpu	`plan_id, duration(1/3/6/12月), os_id, node_uuid, zone, with_eip_num, with_eip_flags, with_eip_type, add_disk_size, disk_type, tag, app_vars[{app_id,vars}]`
rbm	`plan_id, duration, os_id, node_uuid, with_eip_num, with_eip_flags, ipmi_address, rhs_code, rhs_deploy`
rgs	`plan_id, subtype(kvm), pay_mode(month), duration, os_id, config{cpu,memory,net_out,base_disk,data_disk}, with_eip_num, with_eip_flags, online_mode, app_vars`
ros	`plan_id, duration`

displayed_amount 填报价返回的 price。下单成功返回 order_id/order_no/instance_id/amount/status/balance/client_ref；client_ref（≤64 字符）开通后自动回写，可用 GET /instances?client_ref= 反查。

5.4.2 续费（rcs/rgpu/rbm/rgs/ros）实时

报价：GET /instances/:id/renew/quote?product=&duration=1|3|6|12
下单：POST /instances/:id/renew?product=，body：{"client_order_id":"...","duration":1,"price":45.0}

5.4.3 套餐升级 / 变配实时

报价 POST /instances/:id/upgrade/quote?product=，下单 POST /instances/:id/upgrade?product=（幂等）。请求体按产品：

// rcs / rgpu：目标套餐升级（当前套餐由服务端自动查实时详情，无需传）
{ "target_plan_id": 88, "price": 12.3 }

// rgs：游戏云 scale，必须提交完整目标配置；plan_id 不传或为 0 表示保持当前套餐
{ "plan_id": 0,
  "config": { "cpu": 4, "memory": 8, "net_out": 10, "base_disk": 40, "data_disk": 50 },
  "price": 0 }

// ros：对象存储套餐升级（只升不降/同区域/同分组由平台校验）
{ "target_plan_id": 7, "price": 5.0 }

下单时在同级追加 "client_order_id"。rbm 不支持升级。

5.4.4 附加弹性公网 IP（rcs/rgpu）实时

{ "client_order_id": "ip-xxx", "ip_type": "", "count": 1, "price": 20.0 }

ip_type 空串为默认 IPv4；count 1-10，不传按 1。报价/下单：/instances/:id/ips/quote、/instances/:id/ips。

5.4.5 流量加油包（rcs/rgpu）实时

{ "client_order_id": "tf-xxx", "traffic_gb": 100, "price": 15.0 }

可购档位以报价接口返回为准（无档位会报错）。报价/下单：/traffic/quote、/traffic。

5.4.6 硬盘扩容（rcs/rgpu）实时

{ "client_order_id": "de-xxx", "disk_id": 12, "disk_type": "cloud-ssd",
  "add_size": 20, "enable_backup": false, "price": 8.4 }

disk_id 取自 live 详情硬盘列表；系统盘扩容强制带备份（与控制台一致）。
步进：HDD/高效云盘 10GB 起，SSD 类 5GB 起；允许的类型以 live 详情 AvailableDiskType 为准。
价格按剩余天数折算，无额外折扣。

5.4.7 新增硬盘（rcs/rgpu）实时

{ "client_order_id": "da-xxx", "disk_type": "cloud-ssd", "size": 50,
  "enable_backup": false, "tag": "", "price": 33.6 }

报价/下单：/instances/:id/disks/quote、/instances/:id/disks。

5.5 生命周期管控（路径均为 `/instances/:id/...?product=`）实时

方法	路径	请求体 / 参数	支持产品
POST	`/power`	rcs/rgpu：`start/stop`；rbm：`poweron/poweroff` + `stop_mode=soft\|hard`；rgs：`start/stop/reboot`	rcs,rgpu,rbm,rgs
POST	`/reinstall`	`{"os_id":34,"app_vars":[],"reset_osd":true}`（rcs/rgpu）；rgs 用 `"clear_data":true`	rcs,rgpu,rbm,rgs
POST	`/rescue`	`{"action":"enter"}` / `{"action":"exit"}`	rbm
POST	`/password/reset`	rcs/rgpu 可 `{"password":"自定义"}` 或留空随机生成；rgs 仅随机生成（可传 `{}`，忽略 password）；新密码见历史密码接口	rcs,rgpu,rgs
GET	`/vnc`	query `console_type=novnc\|xtermjs`	rcs,rgpu,rgs
PUT	`/tag`	`{"tag":"备注"}`，同步更新平台与本地	rcs,rgpu,rgs,ros
GET	`/monitor`	query `start_date,end_date`（Unix 秒）	rcs,rgpu,rbm,rgs,ros
GET	`/passwords`	分页，历史系统密码	rcs,rgpu,rbm,rgs
GET	`/task-logs`	分页，实例操作日志	rcs,rgpu,rbm,rgs

rgs 的电源与重置密码仅 VPS（KVM）子类型可用；面板服（MCSM 等）请在游戏面板内操作。

5.6 防火墙与 NAT（rcs/rgpu/rgs；rbm/ros 不支持）实时

方法	路径	说明
GET	`/instances/:id/firewall/rules?product=`	规则列表
POST	`/instances/:id/firewall/rules?product=`	新建规则，body 见下
DEL	`/instances/:id/firewall/rules/:rule_id?product=`	删除规则
PUT	`/instances/:id/firewall/rules/:rule_id/position?product=`	`{"position":0}` 调整优先级（从 0 开始）
PUT	`/instances/:id/firewall/mode?product=`	`{"mode":"black"}` 或 `"white"`

{ "action": "accept", "protocol": "tcp", "dest_port": "80",
  "source_address": "0.0.0.0/0", "source_port": "",
  "description": "放行HTTP", "is_enable": true }

NAT 端口映射（映射列表见 live 详情）：

POST   /instances/:id/nat-mappings?product=
DELETE /instances/:id/nat-mappings/:mapping_id?product=

{ "port_type": "tcp", "port_in": 8080, "port_out": 80, "tag": "web" }

port_type：tcp / udp / tcp_udp；端口范围 1-65535。

5.7 备份（rcs/rgpu/rgs）实时

方法	路径	说明
PUT	`/instances/:id/backup/setting?product=`	自动备份策略
POST	`/instances/:id/backups?product=`	手动备份 `{"label":"升级前"}`
POST	`/instances/:id/backups/:backup_id/restore?product=`	还原
DEL	`/instances/:id/backups/:backup_id?product=`	删除备份
POST	`/instances/:id/backups/:backup_id/cancel?product=`	取消进行中的备份任务

{ "enabled": true, "hour": 3, "minute": 30, "keep_last": 7 }

rcs/rgpu：keep_last 仅接受 0/1/3/7/15/31；关闭时服务端自动传 -1。
rgs：keep_last 1-7；关闭时 hour/minute 自动传 -1。
备份列表从 /instances/:id/live 实时详情获取。

5.8 弹性公网 IP / 其他开关实时

方法	路径	body	支持
POST	`/instances/:id/ip/change?product=`	`{"ip":""}`（空=自动分配新 EIP）	rcs,rgpu
POST	`/instances/:id/ip/discard?product=`	`{"ip":"1.2.3.4"}`（不可恢复）	rcs,rgpu
PUT	`/instances/:id/ip/description?product=`	`{"ip":"1.2.3.4","description":"主站"}`（≤50 字）	rcs,rgpu
POST	`/instances/:id/cpu-limit-mode?product=`	`{"mode":true}` 限制 CPU 超额	rgs
POST	`/instances/:id/public-access/toggle?product=`	无（翻转当前公共访问状态）	ros
POST	`/instances/:id/extra-accounting?product=`	`{"enable":true}` 超额计量开关	ros

5.9 ROS 对象存储：桶与对象实时

方法	路径	说明
GET	`/instances/:id/buckets?product=ros`	该实例下全部桶（分页 ≤100）
POST	`/instances/:id/buckets?product=ros`	创建桶 `{"name":"my-bucket"}`（3-63 位小写字母/数字/中划线）
GET	`/buckets/:bucket_id`	桶详情（含桶级 AK/SK、WAF/Gzip/黑白名单配置）
DEL	`/buckets/:bucket_id?confirm=true`	删除空桶，不可恢复

S3 直连架构：文件内容不经过平台服务器，平台只负责鉴权和签名，客户端拿预签名 URL 直传/直下载。

方法	路径	说明
GET	`/buckets/:bucket_id/objects?prefix=down/`	列某层目录（文件夹以 `/` 结尾）
POST	`/buckets/:bucket_id/objects/mkdir`	`{"prefix":"","name":"abc"}` 建文件夹
DEL	`/buckets/:bucket_id/objects?key=down/a.apk`	删文件；key 以 `/` 结尾时递归删整个文件夹
POST	`/buckets/:bucket_id/objects/batch-delete`	`{"keys":["a.zip","dir/"]}` 批量删除（文件夹递归）
GET	`/buckets/:bucket_id/objects/presign?key=down/a.apk`	返回 `get_url/put_url/base_url`（3600 秒）
POST	`/buckets/:bucket_id/objects/direct-upload-sign`	`{"prefix":"down/","name":"a.zip"}` 直传 PUT URL（3600 秒）
POST	`/buckets/:bucket_id/objects/batch-presign`	`{"keys":[...]}` 批量下载地址（9600 秒，文件夹自动忽略）

大文件对接建议：先 direct-upload-sign 取 URL → 客户端直接 PUT 到 S3 → 分享时用 presign / batch-presign 取下载地址。

5.10 订单（本地数据）

方法	路径	说明
GET	`/orders`	分页 `page/page_size/status`
GET	`/orders/:id`	订单详情
POST	`/orders/:id/cancel`	仅待支付（pending）订单可取消，取消后状态 closed

订单状态：pending / paid / refunded / closed 等，以返回的 status 字符串为准。

6. 产品能力矩阵

能力	rcs	rgpu	rbm	rgs	ros
新购 / 续费 / 释放 / 标签 / 监控	✅	✅	✅	✅	✅
开机/关机	✅	✅	✅ soft/hard	✅ 含重启（仅 VPS）	❌
重装系统	✅	✅	✅	✅ 可清数据盘	❌
救援模式	❌	❌	✅	❌	❌
重置密码	✅	✅	❌	✅ 随机生成（仅 VPS）	❌
VNC	✅	✅	❌	✅	❌
历史密码 / 任务日志	✅	✅	✅	✅	❌
防火墙 / NAT	✅	✅	❌	✅	❌
备份	✅	✅	❌	✅	❌
附加 IP / 换 IP / 流量包 / 硬盘	✅	✅	❌	❌	❌
套餐升级变配	✅	✅	❌	✅ scale	✅
CPU 超额限制	❌	❌	❌	✅	❌
公共访问开关 / 超额计量 / 桶与对象	❌	❌	❌	❌	✅

对不支持的能力调用会返回 400 unsupported_product_action。

7. 推荐对接流程

开通：/catalog/* 选套餐节点 → POST /quotes 报价 → 商户后台确认 → POST /instances（带 client_order_id、client_ref）。
异步判定结果：下单接口同步返回成功即已开通；失败自动退款。商户侧持久化 client_order_id → order_id/instance_id，网络超时直接用同号重试（幂等重放）。
资源同步：用 GET /instances?client_ref= 或 GET /instances/:id/live 拉状态/IP；不要高频轮询，操作类动作后建议间隔 3-5 秒再查。
续费/升级/加购：一律先走 quote，把 price 原样回传下单。
资金：余额充值在平台网站控制台完成，用 /finance/transactions 与自有账单对账；捕获 insufficient_balance 时引导商户去网页端充值。
ROS：业务文件全部走预签名 URL 直传直下，平台 API 只做桶管理与签名，不要把文件流打到本 API。
重试策略：429 按 Retry-After 退避；502 service_error 可幂等重试查询/报价；扣款类请求超时一律用原 client_order_id 重发，不要换号。

8. 备注

全部金额单位为人民币元；时间戳均为 Unix 秒。
所有错误信息均为可直接展示的中文提示，不含平台内部实现细节。
分页参数统一 page（从 1 开始）、page_size（默认 20，最大 100）。
密钥管理（创建/停用/删除/IP 白名单）在账号内的「开放平台」页面自助操作，开放 API 自身不提供密钥管理端点；Secret 遗失请删除旧密钥后重新创建。

开放 API v1 接入文档

概览

1. 鉴权（HMAC-SHA256 签名）

1.1 请求头

1.2 签名算法

1.3 curl 示例（GET）

1.4 鉴权错误

2. 限流（两级）

3. 幂等（资金类操作必做）

4. 响应信封与错误码

5. 接口清单

5.1 账号与资金

5.2 目录（公开数据）实时

5.3 实例

5.4 新购与资金变配（统一“先报价、后下单”）

5.4.1 新购

5.4.2 续费（rcs/rgpu/rbm/rgs/ros）实时

5.4.3 套餐升级 / 变配 实时

5.4.4 附加弹性公网 IP（rcs/rgpu）实时

5.4.5 流量加油包（rcs/rgpu）实时

5.4.6 硬盘扩容（rcs/rgpu）实时

5.4.7 新增硬盘（rcs/rgpu）实时

5.5 生命周期管控（路径均为 /instances/:id/...?product=）实时

5.6 防火墙与 NAT（rcs/rgpu/rgs；rbm/ros 不支持）实时

5.7 备份（rcs/rgpu/rgs）实时

5.8 弹性公网 IP / 其他开关 实时

5.9 ROS 对象存储：桶与对象 实时

5.10 订单（本地数据）

6. 产品能力矩阵

7. 推荐对接流程

8. 备注

5.4.3 套餐升级 / 变配实时

5.5 生命周期管控（路径均为 `/instances/:id/...?product=`）实时

5.8 弹性公网 IP / 其他开关实时

5.9 ROS 对象存储：桶与对象实时