用户查询接口
接口说明
用户信息查询接口,通过公共参数 appId 和 subMerchantNo 查询用户的余额和积分信息。
适用对象
间连商户
请求 URL
https://openapi.shuhuipay.com/v1/user/query请求方法
POST
接口说明:
- 该接口用于查询指定用户的余额和积分
- 通过公共参数
appId和subMerchantNo定位用户,无需额外业务参数 - 返回的余额单位为元,精确到小数点后两位(数据库存储单位为分)
请求参数
无额外业务参数:
该接口无需在 bizContent 中传递额外参数,直接使用公共参数 appId 和 subMerchantNo 进行查询。
请求示例
JSON
{
"appId": "your_system_appid",
"subMerchantNo": "your_sub_merchant_no",
"bizContent": "{}",
"version": "1.0",
"nonce": "49d55020fa3adf6ed67b253c583ccdaa",
"contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
"timestamp": "2026-08-05 10:00:00",
"sign": "your_sign"
}
响应参数
公共返回参数
| 参数 | 类型 | 必须 | 参数说明 |
|---|---|---|---|
code |
String | Y | 响应状态码,成功 0000 |
message |
String | Y | 响应描述 |
timestamp |
String | Y | 响应时间戳,UTC 时间,ISO 8601 格式 |
data |
Object | Y | 业务数据,无数据时返回空对象 {} |
响应附加参数(data)
| 参数名 | 类型 | 必填 | 参数说明 |
|---|---|---|---|
money |
String | Y | 账户余额(元),精确到小数点后两位,如 "100.50" |
score |
String | Y | 用户积分,精确到小数点后两位,如 "100.50" |
响应示例
成功响应:
JSON
{
"code": "0000",
"message": "查询成功",
"timestamp": "2026-08-05T10:00:00.000Z",
"data": {
"money": "100.50",
"score": "100.50"
}
}
失败响应:
JSON
// 用户不存在
{
"code": "4004",
"message": "用户不存在或已禁用",
"timestamp": "2026-08-05T10:00:00.000Z",
"data": {}
}
// appId 未关联用户
{
"code": "4003",
"message": "appId 未关联有效用户",
"timestamp": "2026-08-05T10:00:00.000Z",
"data": {}
}
错误码说明
| 错误码 | 说明 |
|---|---|
0000 |
成功 |
4003 |
无权操作(appId 未关联有效用户) |
4004 |
数据不存在(用户不存在或已禁用) |
5000 |
系统异常 |
代码示例
Java
import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;
public class UserQueryExample {
public static void main(String[] args) {
String result = queryUserInfo();
System.out.println("查询结果:" + result);
}
public static String queryUserInfo() {
String appId = "your_app_id";
String subMerchantNo = "your_sub_merchant_no";
String signKey = "your_sign_key";
String apiUrl = "https://openapi.shuhuipay.com/v1/user/query";
Map<String, String> requestData = new HashMap<>();
requestData.put("appId", appId);
requestData.put("subMerchantNo", subMerchantNo);
requestData.put("bizContent", "{}");
requestData.put("version", "1.0");
requestData.put("nonce", "49d55020fa3adf6ed67b253c583ccdaa");
requestData.put("contentHash", "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382");
requestData.put("timestamp", "2026-08-05 10:00:00");
String sign = SignUtil.generateSign(requestData, signKey);
requestData.put("sign", sign);
String response = HttpUtil.post(apiUrl, requestData);
return response;
}
}
Python
import requests
import json
import hashlib
def query_user_info():
"""查询用户信息"""
sys_appid = "your_sys_appid"
sub_merchant_no = "your_sub_merchant_no"
sign_key = "your_sign_key"
api_url = "https://openapi.shuhuipay.com/v1/user/query"
request_data = {
"appId": sys_appid,
"subMerchantNo": sub_merchant_no,
"version": "1.0",
"timestamp": "2026-08-05 10:00:00",
"nonce": "49d55020fa3adf6ed67b253c583ccdaa",
"bizContent": "{}",
"contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
}
sign = generate_sign(request_data, sign_key)
request_data["sign"] = sign
try:
response = requests.post(api_url, json=request_data, timeout=30)
return response.json()
except Exception as e:
print(f"查询失败: {e}")
return None
def generate_sign(params, sign_key):
sorted_params = sorted(params.items())
sign_str = "&".join([f"{k}={v}" for k, v in sorted_params if v])
sign_str += f"&key={sign_key}"
return hashlib.md5(sign_str.encode()).hexdigest().upper()
# 查询用户信息
result = query_user_info()
# 处理返回结果
if result and result.get("code") == "0000":
data = result.get("data", {})
print(f"余额: {data.get('money')} 元")
print(f"积分: {data.get('score')}")
PHP
<?php
class UserQuery {
private $appId = 'your_app_id';
private $subMerchantNo = 'your_sub_merchant_no';
private $signKey = 'your_sign_key';
private $apiUrl = 'https://openapi.shuhuipay.com/v1/user/query';
public function queryUserInfo() {
$requestData = [
'appId' => $this->appId,
'subMerchantNo' => $this->subMerchantNo,
'bizContent' => '{}',
'version' => '1.0',
'nonce' => '49d55020fa3adf6ed67b253c583ccdaa',
'contentHash' => '95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382',
'timestamp' => '2026-08-05 10:00:00',
];
$requestData['sign'] = $this->generateSign($requestData);
$response = $this->httpPost($this->apiUrl, $requestData);
return json_decode($response, true);
}
private function generateSign($params) {
ksort($params);
$signStr = '';
foreach ($params as $key => $value) {
if ($value !== '') {
$signStr .= "{$key}={$value}&";
}
}
$signStr .= "key={$this->signKey}";
return strtoupper(md5($signStr));
}
private function httpPost($url, $data) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);
return $response;
}
}
// 查询用户信息
$result = (new UserQuery())->queryUserInfo();
// 处理返回结果
if ($result && $result['code'] === '0000') {
$data = $result['data'] ?? [];
echo "余额: " . ($data['money'] ?? '0.00') . " 元" . PHP_EOL;
echo "积分: " . ($data['score'] ?? 0) . PHP_EOL;
}
注意事项
权限限制:
- 只能查询当前
appId和subMerchantNo对应用户的信息 - 参数不匹配将返回
4003错误码 - 已禁用的用户无法查询,返回
4004错误码
查询说明:
- 系统通过公共参数
appId和subMerchantNo定位用户 - 余额返回单位为元,精确到小数点后两位(数据库存储单位为分)
- 返回字段仅包含
money(余额)和score(积分)
最佳实践:
- 确保
appId和subMerchantNo参数正确,否则查询将失败 - 敏感信息(如余额)请做好前端展示脱敏处理
- 查询频率建议控制在合理范围内,避免频繁调用