# 变更详情与折算预览
变更详情接口用于在发起变更前预览折算明细，包含新旧计划对比、剩余价值折算、差额与生效时间等信息。本接口不产生实际变更，仅计算并返回预览数据，供商户系统展示。
# 商户预检接口
接口
请求API: /api/subscription/change/detail
请求方式: POST
请求类型：application/json 或 application/x-www-form-urlencoded
# 请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户号 | mchNo | 是 | String(30) | M1621873433953 | 商户号 |
| 应用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 应用ID |
| 订阅ID | subscriptionId | 是 | String(32) | SUB_20210618164232 | 订阅ID |
| 目标计划ID | newPlanId | 否 | String(32) | PLAN_002 | 目标订阅计划ID，与newPlanCode二选一 |
| 目标计划编码 | newPlanCode | 否 | String(64) | PRO_MONTH | 目标订阅计划编码，与newPlanId二选一 |
| 变更类型 | changeType | 是 | String(20) | UPGRADE | 变更类型：UPGRADE-升级 / DOWNGRADE-降级 |
| 生效方式 | effectiveType | 是 | String(20) | IMMEDIATE | 生效方式：IMMEDIATE-立即生效 / NEXT_PERIOD-下期生效 |
| 请求时间 | reqTime | 是 | long | 1622016572190 | 请求接口时间,13位时间戳 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
| 签名类型 | signType | 是 | String(32) | MD5 | 签名类型，目前只支持MD5方式 |
# 请求示例数据
{
"mchNo": "M1623984572",
"appId": "60cc09bce4b0f1c0b83761c9",
"subscriptionId": "SUB_20210618164232",
"newPlanId": "PLAN_002",
"changeType": "UPGRADE",
"effectiveType": "IMMEDIATE",
"reqTime": "1622016572190",
"version": "1.0",
"signType": "MD5",
"sign": "84F606FA25A6EC4783BECC08D4FDC681"
}
目标计划传参
newPlanId 与 newPlanCode 二选一即可。示例以 newPlanId 演示，商户也可改用 newPlanCode（如 "newPlanCode": "PRO_MONTH"）定位目标计划，系统将自动按当前订阅的 mchNo/appId/currency 解析为对应的 planId。
# 返回参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态 | code | 是 | int | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | msg | 否 | String(128) | 签名失败 | 具体错误原因 |
| 签名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 对data内数据签名 |
| 返回数据 | data | 否 | Object | {} | 返回变更详情数据 |
# data数据格式 (SubscriptionChangeDetailRS)
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 订阅ID | subscriptionId | String | SUB_20210618164232 | 订阅ID |
| 商品名称 | subject | String | 会员订阅 | 订阅商品名称 |
| 原计划ID | oldPlanId | String | PLAN_001 | 原订阅计划ID |
| 原计划名称 | oldPlanName | String | 基础月度会员 | 原订阅计划名称 |
| 原计划编码 | oldPlanCode | String | BASIC_MONTH | 原订阅计划编码 |
| 原计划周期单位 | oldPlanIntervalUnit | String | MONTH | 原计划周期单位：DAY/WEEK/MONTH/YEAR |
| 原计划周期数量 | oldPlanIntervalCount | Integer | 1 | 原计划周期数量 |
| 原计划本期金额 | oldAmount | Long | 1000 | 原计划本期金额，单位分 |
| 新计划ID | newPlanId | String | PLAN_002 | 新订阅计划ID |
| 新计划名称 | newPlanName | String | 高级月度会员 | 新订阅计划名称 |
| 新计划编码 | newPlanCode | String | PRO_MONTH | 新订阅计划编码 |
| 新计划周期单位 | newPlanIntervalUnit | String | MONTH | 新计划周期单位：DAY/WEEK/MONTH/YEAR |
| 新计划周期数量 | newPlanIntervalCount | Integer | 1 | 新计划周期数量 |
| 新计划本期金额 | newAmount | Long | 2500 | 新计划本期金额，单位分 |
| 变更类型 | changeType | String | UPGRADE | UPGRADE-升级 / DOWNGRADE-降级 |
| 生效方式 | effectiveType | String | IMMEDIATE | IMMEDIATE-立即生效 / NEXT_PERIOD-下期生效 |
| 预计生效时间 | effectiveTime | Date | 1622016572190 | 预计生效时间戳 |
| 折算剩余价值 | remainingValue | Long | 600 | 当前周期剩余价值折算，单位分 |
| 差额 | diffAmount | Long | 1500 | 差额，单位分，正数表示需补付 |
| 已使用天数 | prorateDaysUsed | Integer | 12 | 当前周期已使用天数 |
| 总天数 | prorateDaysTotal | Integer | 30 | 当前周期总天数 |
| 币种 | currency | String | USD | 币种 |
| 是否跳过优惠期 | trialSkipped | Boolean | false | 是否跳过了新计划优惠期（已享受过优惠期时为true） |
# 返回示例数据
{
"code": 0,
"msg": "SUCCESS",
"data": {
"subscriptionId": "SUB_20210618164232",
"subject": "会员订阅",
"oldPlanId": "PLAN_001",
"oldPlanName": "基础月度会员",
"oldPlanCode": "BASIC_MONTH",
"oldPlanIntervalUnit": "MONTH",
"oldPlanIntervalCount": 1,
"oldAmount": 1000,
"newPlanId": "PLAN_002",
"newPlanName": "高级月度会员",
"newPlanCode": "PRO_MONTH",
"newPlanIntervalUnit": "MONTH",
"newPlanIntervalCount": 1,
"newAmount": 2500,
"changeType": "UPGRADE",
"effectiveType": "IMMEDIATE",
"effectiveTime": 1622016572190,
"remainingValue": 600,
"diffAmount": 1500,
"prorateDaysUsed": 12,
"prorateDaysTotal": 30,
"currency": "USD",
"trialSkipped": false
},
"sign": "F4DA202C516D1F33A12F1E547C5004FD"
}
# 折算说明
折算规则
- 剩余价值折算：立即生效变更时，系统按当前周期已使用天数比例折算原计划剩余价值，用于抵扣新计划费用。
- 差额计算：
diffAmount = 新计划本期金额 - 折算剩余价值。差额大于 0 时需用户补付，差额为 0 或负数时无需补付。 - 优惠期跳过：若用户已享受过订阅优惠期，切换到含优惠期的新计划时将跳过优惠期，按标准期计费（
trialSkipped=true）。