API指南

接入信息

接口前缀：/api/v1/partner
正式环境：https://api.easysub.site

在“账号设置 → API 对接”生成并保存密钥，请求头携带：

JSON 请求携带 Content-Type。Apifox 中填写环境变量 api_key，仅填写密钥本身。

密钥生成时展示一次；重新生成后旧密钥立即失效。接口操作范围为账号当前组织，同组织账号可访问相同支付卡和 API 任务；具体操作需具备相应权限。

响应约定

业务响应使用 HTTP 200，先检查 status_code，再读取 data。

{"status_code":0,"msg":"success","data":[]}

status_code	含义
0	调用成功
400	参数或业务条件错误
401	密钥或账号状态失效
403	权限不足
409	幂等键对应的请求参数发生变化
500	服务异常

错误说明见 msg；联系支持时可附带响应中的 request_id。

分页接口返回 pagination。page 默认 1，page_size 默认 20、最多 500。时间采用 ISO 8601 格式；金额以对应币种的最小单位表示。

方案与支付方式

查询方案：GET /plans，返回所有启用方案。

数字 id：用于支付卡管理的 checkout_profile_id。

字符串 plan_id：用于提交订阅任务。仅选择非空值。

支付方式	请求内容
platform	`payment_method` 填写 `{"type":"platform"}`，使用已管理的支付卡。
custom	填写 `type=custom`、卡号、MM/YY 有效期和 CVC，使用本次提交的卡片。

支付卡管理接口用于管理 platform 卡片。登录态格式及请求示例见《登录态与订阅调用示例》。

提交与查询任务

查询方案并选择非空 plan_id。

准备对应服务商的登录态，生成并保存 idempotency_key。

调用 POST /subscriptions，成功后保存 order_no。

调用 GET /subscriptions/{order_no}，建议每 3～5 秒查询一次。

status	含义	处理
processing	处理中	继续查询原订单。
success	成功	停止轮询。
manual_success	已完成	停止轮询。
failed	失败	停止轮询，查看 error。

status_code=0 表示接口调用成功，任务最终结果以 data.status 为准。处理中出现 error 提示时继续查询原订单。

幂等与重试

idempotency_key 必填，最多 160 字节，建议使用 UUID 或调用方业务单号。

同一账号、同一键、相同请求参数返回原订单；参数变化返回 409。提交超时或响应丢失时，使用原参数和原幂等键重试。新任务使用新键。

支付卡管理

支付卡支持列表、详情、新增、修改、删除、批量导入、批量修改、启停及使用记录查询。

卡号和 CVC 查询时返回脱敏值。

新增或导入默认总次数为 1、优先级为 100、状态为 enabled；优先级越大越优先。

关联方案使用方案查询返回的数字 id；账单地址使用已有 ID。

导入模板通过 GET /payment-card-import-templates 查询，支持分页和关键词搜索。将返回的 id 填入 template_id，按 template 格式填写 text，并设置 import_mode=template。

修改卡片时提交完整配置；省略配置会使用默认值或清空关联。卡号和 CVC 省略或留空时保留原值，请勿提交脱敏值。

修改部分字段使用 bulk-update，通过 fields 指定修改项。

批量操作的卡片 ID 须有效、属于当前组织且互不重复。

批量导入最多 500 张，重复卡或无效数据导致整批失败；格式见接口参数。

停用或删除卡片影响后续使用，已有订单继续处理；历史使用记录保留。

接入信息#

响应约定#

方案与支付方式#

提交与查询任务#