用户状态查询
更新时间：2024.11.14应用场景
在停车场、高速、加油等场景下，商户需获取用户车主服务状态/需要关联车主服务。本接口，会查询用户是否开通、授权、有欠费或黑名单用户情况，并将对应的用户状态进行返回。
流程介绍
调用用户状态查询api获取当前用户车主状态，如果当前用户车主状态异常（如有欠费(OVERDUE)，未授权(UNAUTHORIZED)，校验授权关系失败(VEHICLE_AUTH_ERROR)），
接口同步返回跳转路径(path字段)商户侧需根据步骤2引导用户进入车主服务进行相关操作；如果当前用户车主状态正常，不会返回path字段，不需要再引导用户进入车主服务– 小程序,APP跳转，通过跳转路径(path)调用 ‘用户授权/开通接口api’ 进入车主小程序的对应页面，用户进行授权/开通的操作
– H5跳转，通过跳转路径(path)调用 ‘用户授权/开通接口api’ 进入车主H5对应的页面，用户进行授权/开通操作返回商户小程序,APP或H5页面后再次调用用户状态查询api确认用户最新车主状态及车牌信息
接口链接
https://api.mch.weixin.qq.com/vehicle/partnerpay/querystate
是否需要证书
不需要
请求参数
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
公众账号id | appid | 是 | String（32） | wxcbda96de0b165486 | 服务商商户号绑定的APPID |
子商户公众账号id | sub_appid | 是 | String（32） | wxcbda96de0b165489 | 子商户号绑定的服务号，小程序，APP的appid(需要在服务商的商户平台为子商户绑定) |
商户号 | mch_id | 是 | String（32） | 10000098 | 服务商商户号 |
子商户号 | sub_mch_id | 是 | String（32） | 1900000109 | 子商户号 |
随机字符串 | nonce_str | 是 | String（32） | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 随机字符串，不长于32位。 |
签名类型 | sign_type | 是 | String（32） | HMAC-SHA256 | 签名类型，默认为HMAC-SHA256 |
签名 | sign | 是 | String（64） | EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5 | 签名，详见签名生成算法 |
交易场景 | trade_scene | 是 | String（16） | PARKING | 委托代扣的交易场景值，目前支持 ： PARKING：车场停车场景 ； PARKING SPACE 车位停车场景； GAS 加油场景； HIGHWAY 高速场景； 该值会向微信用户进行展示 |
跳转场景 | jump_scene | 否 | String（16） | H5 | 商户跳转的业务场景，不传默认是小程序，也支持APP和公众号H5跳转
APP:通过APP跳转 H5:通过公众号H5跳转 |
用户标识 | openid | 三选一 | String（32） | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o | 用户在商户appid下的唯一标识。 |
用户子标识 | sub_openid | String（32） | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o | 用户在子商户appid下的唯一标识。 | |
车牌号 | plate_number | String（32） | 粤B888888 | 车牌号。仅包括省份+车牌，不包括特殊字符。 | |
版本号 | version | 是 | String（16） | 3.0 | 版本号，固定值 |
举例如下：
返回结果
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
返回状态码 | return_code | 是 | String（16） | SUCCESS | SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看user_state来判断 |
返回信息 | return_msg | 否 | String（128） | 签名失败 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
请求appid | appid | 是 | String（32） | wxcbda96de0b165486 | appid是商户在微信申请公众号或移动应用成功后分配的账号ID，登录平台为mp.weixin.qq.com或open.weixin.qq.com |
子商户公众账号id | sub_appid | 否 | String（32） | wxcbda96de0b165489 | 微信分配的子商户公众账号ID |
商户号 | mch_id | 是 | String（32） | 10000098 | 商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com |
子商户号 | sub_mch_id | 是 | String（32） | 1900000109 | 微信支付分配的子商户号 |
随机字符串 | nonce_str | 是 | String（32） | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 随机字符串，不长于32位。推荐随机数生成算法 |
签名 | sign | 是 | String（64） | EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5 | 签名，详见签名生成算法 |
业务结果 | result_code | 是 | String（16） | SUCCESS | SUCCESS/FAIL |
错误代码 | err_code | 否 | String（32） | SYSTEMERROR | 错误码 |
错误代码描述 | err_code_des | 否 | String（128） | 系统错误 | 结果信息描述 |
当return_code 和result_code都为SUCCESS的时，还会包括以下字段：
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 | |||
|---|---|---|---|---|---|---|---|---|
用户状态 | user_state | 是 | String（16） | NORMAL | NORMAL：正常用户，已开通车主服务，且已授权访问 PAUSED：已暂停车主服务 OVERDUE: 用户已开通车主服务，但欠费状态。提示用户还款，请跳转到车主服务 UNAUTHORIZED：用户未授权使用当前业务，或未开通车主服务。请跳转到授权接口 | |||
用户标识 | openid | 否 | String（32） | oUpF8uMuAJO_M2pxb1Q9zNjWeS69 | 用户在商户appid下的唯一标识，当用户入驻车主平台时进行返回 | |||
发起扣费方式 | deduct_mode | 否 | String（16） | PROACTIVE | 发起扣费的方式 | |||
用户子标识 | sub_openid | 否 | String（32） | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o | sub_appid下，用户的唯一标识 | |||
跳转路径 | path | 否 | String（1024） | pages/route/index | 跳转车主小程序的页面路径，如果该参数返回不为空，商户侧需调用‘用户授权/开通接口’引导用户进入车主小程序进行授权/开通的操作，‘用户授权/开通接口’请查看下面的详细说明; H5跳转同理 | |||
车牌信息 | plate_number _info | 否 | String（512） | {"plate_number_info":[{"plate_number":"粤B888888","channel_type":"ETC"}]} | 车牌号列表。仅包括省份+车牌，不包括特殊字符。 | |||
| ||||||||
举例如下：
错误码
名称 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
SYSTEMERROR | 接口返回错误 | 系统超时 | 请使用相同参数再次调用API |
PARAM_ERROR | 参数错误 | 请求参数未按指引进行填写 | 请根据接口返回的详细信息检查您的程序 |
INVALID_REQUEST | 非法请求 | 非法请求 | 请检查请求参数、商户权限等是否正确 |
VEHICLE_NOT_EXIST | 当前车牌尚未绑定车主平台 | 当前用户未在车主服务中，绑定该车牌 | 请检查车牌号是否正确 |
PAYAUTH_ERROR | 权限校验错误 | 商户号产品权限校验错误 | 请检查商户号代扣产品权限 |
