Table of Contents
18.3 请求头与版本策略
18.3.1 iOS/Android 请求头
所有进入 /tieup/api/v1/** 的 APP 业务请求均应携带：
| 请求头 | 是否必填 | 说明 |
|---|---|---|
X-App-Channel |
是 | 渠道代码，1～50 字符，仅允许字母、数字、点、下划线、短横线 |
X-App-Platform |
是 | ios 或 android |
X-App-Version |
是 | 版本名称，必须与后台版本记录完全一致 |
X-App-Build |
是 | 1～4294967295 的整数构建号 |
X-Device-Id |
是 | 稳定设备标识，最多 128 字符 |
X-Session-Id |
密文请求必填 | 握手返回的 Session ID |
服务端使用 X-App-Channel + X-App-Platform + X-App-Build 精确查询版本，再校验 X-App-Version。缺少请求头、未知版本或版本名称不一致统一返回 4609，不能伪装成“未开启加密”的旧版本绕过策略。
18.3.2 H5 请求头
H5 请求携带：
| 请求头 | 是否必填 | 说明 |
|---|---|---|
X-App-Channel |
是 | 当前 H5 渠道代码 |
X-App-Platform |
是 | 固定为 h5 |
X-Device-Id |
是 | 浏览器端稳定生成并持久化的设备标识，最多 128 字符 |
X-Session-Id |
密文请求必填 | 握手返回的 Session ID |
H5 不查询 APP 版本表，服务端内部版本名称为空、构建号固定为 0。H5 可以发送 X-App-Version、X-App-Build 用于其他业务日志，但它们不参与本协议策略和 AAD。
18.3.3 开关行为
| 客户端 | 强制开关关闭 | 强制开关开启 |
|---|---|---|
| iOS/Android | 版本头仍须合法；接受现有明文和合法密文 | GET、JSON 写请求必须使用密文 |
| H5 | H5 Key 已配置时接受明文和合法密文；Key 为空时只能明文且不能握手 | 必须配置 32 字节 H5 Key，GET、JSON 写请求必须使用密文 |
强制模式下发送明文返回 4606。兼容模式不是跳过版本校验；APP 的版本头始终必须合法。