小程序校验接口

接口功能

根据用户环境，校验小程序能否正常分发

URL

https://openapi.baidu.com/rest/2.0/smartapp/SsproxyMetaService/valid

调用方式

POST

是否可重入

是

支持数据格式

JSON

参数说明

参数名	类型	必填	说明
access_token	String	是	access_token 获取方式详见接入说明

请求体说明

参数名	类型	必填	说明
comm_params	Object	是	请求用户的公参信息
retrieve_params	Object	是	请求小程序的相关信息，支持批量校验，批量度建议不超过 20

comm_params 对象

字段	类型	必填	说明
uuid	String	是	用户唯一标识符
host_os	String	是	设备操作系统，可选: “ios” 或 “android”
host_os_ver	Object	是	操作系统版本，ver_str 字段格式为 a.b.c.d 四段式
host_app_ver	Object	是	宿主版本，ver_str 字段格式为 a.b.c.d 四段式
sdk_ver	Object	是	小程序SDK版本，ver_str 字段格式必须为 a.b.c 三段式
framework_ver	Object	是	小程序基础框架版本，ver_str 字段格式必须为 a.b.c 三段式
swan_game_ver	Object	否	小游戏基础框架版本，ver_str 字段格式必须为 a.b.c 三段式
manu_capital	String	否	厂商大写字母，例如：HUAWEI、XIAOMI
model	String	否	设备机型，例如：VOG-AL00、iPhone10,1
header_ua	String	是	Header 中的 User-Agent

上述所有字段名为 *_ver 的版本类型，其结构体内包含字段如下表：

字段	类型	说明
ver_str	String	字符串类型版本号，如 “12.4.0”

注意：

操作系统版本（host_os_ver）和宿主版本（host_app_ver）的 ver_str 字段允许传入 N 段式（0 < N ≤ 4），接口内部会进行兼容处理(补零)；
对于小程序 SDK 版本（sdk_ver）、小程序基础框架版本（framework_ver）、小游戏基础框架版本（swan_game_ver），请务必按照规定的三段式传入。

对操作系统版本（host_os_ver）和宿主版本（host_app_ver）ver_str 字段的兼容处理策略示例如下表：

ver_str 字段示例	说明
“4.3.2.1”	符合规范，不做兼容处理
“2”	进行兼容处理，自动补零为 “2.0.0.0”
“2.1”	进行兼容处理，自动补零为 “2.1.0.0”

user_ip 对象

字段	类型	说明
ip_str	String	字符串格式的 ip 地址，支持 ipv4 和 ipv6

retrieve_params 对象

字段	类型	必填	说明
retrieve_key	String	是	检索 key 值，即小程序的 app_key
version	Object	否	本地小程序版本，结构体内部字段同 *_ver
app_uid	Object	是	小程序唯一标识

app_uid 对象

字段	类型	说明
open_bundle_id	String	小程序唯一标识，由数字、大小写字母组成

请求示例 POST/JSON

{
    "comm_params":{
        "uuid":"deviceid|imei",
        "host_os":"ios",
        "host_os_ver":{
            "ver_str":"9.0.0.0"
        },
        "user_ip":{
            "ip_str":"2409:8a3c:7d08:e10:8408:248f:14f3:8ecc"
        },
        "host_app_ver":{
            "ver_str":"1.0.0.0"
        },
        "sdk_ver":{
            "ver_str":"2.0.0"
        },      
        "framework_ver":{
            "ver_str":"3.1.1"
        },
        "swan_game_ver":{
            "ver_str":"1.2.0" 
        },
        "manu_capital":"HUAWEI",
        "model":"INE-AL00",
        "header_ua":"User-Agent: Mozilla/<version> (<system-information>) <platform> (<platform-details>) <extensions>"
    },
    "retrieve_params":[
        {
            "retrieve_key":"B0This1iS2the3tEst4app5KEy6for7Api",
            "version":{
                "ver_str":"0"
            },
            "app_uid":{
                "open_bundle_id":"B0This1iS2the3tEst4app5KEy6for7Api"
            }
        },
        {
            "retrieve_key":"B7This6iS5the4tEst3app2KEy1for0Api",
            "version":{
                "ver_str":"0"
            },
            "app_uid":{
                "open_bundle_id":"B7This6iS5the4tEst3app2KEy1for0Api"
            }
        }
    ]
}

返回字段

字段	类型	描述
err_no	Int	外部错误码，标记本次请求是否成功。0表示请求成功, 但对小程序的校验结果不依赖本字段
err_msg	String	请求的返回信息描述
valid_resp	Object	校验结果，描述校验的每个小程序的结果

外部错误码说明

错误码	说明
0	请求成功
1 或 32768000 或 32833536 或 19660800	系统错误
2 或 6553600	参数错误，请确认请求参数后重试

注意：
1、只有当外部错误码为 0 时，请求校验服务成功。
2、若外部错误码显示请求失败（系统错误或其他未列举出的错误码），建议按照正常业务逻辑处理，本次请求结果不作为是否下发小程序的判断依据。

valid_resp 对象

字段	类型	描述
err_no	enum	小程序校验结果错误码
err_msg	String	校验结果信息描述
retrieve_key	String	请求传入的检索 key 值，与小程序校验结果错误码和描述信息一一对应
request_id	int64	请求标识

校验结果说明

错误码	说明	能否分发
0	校验成功	能
3	包不存在	不能
4	需要升级小程序 SDK 版本	建议不分发
5	小程序框架升级	能
6	宿主不支持	不能
7	小程序校验失败	不能

请求成功示例

{
    "err_no": 0,      # 外部错误码，标记请求是否成功
    "err_msg": "Valid Success.",
    "valid_resp": [
        {
            "err_no": 3,      # 小程序校验结果错误码，标记小程序校验结果
            "err_msg": "Package Is Not Exist.",
            "retrieve_key": "B0This1iS2the3tEst4app5KEy6for7Api"
        },
        {
            "err_no": 0,      # 小程序校验结果错误码，标记小程序校验结果
            "err_msg": "Valid Success.",
            "retrieve_key": "B7This6iS5the4tEst3app2KEy1for0Api"
        }
    ],
    "request_id" : 123
}

请求失败（未成功请求到校验服务）示例

{
    "error_code": 110,
    "error_msg": "Access token invalid or no longer valid"
}

请求失败（请求到校验服务但外部错误码非 0）示例

{
    "err_no": 32833536,     # 外部错误码显示请求失败，建议按正常业务逻辑处理
    "err_msg": "rpc failed"
}

注：成功请求校验服务时，错误码字段名为 “err_no” 。未能成功请求到校验服务时，错误码字段名为 “error_code” ，这表示失败原因与 OpenApi 相关，更多 OpenApi 相关错误码详见 OpenApi 返回状态码说明。

反馈建议