用户查询接口

更新时间:2026-08-05

接口说明

用户信息查询接口,通过公共参数 appIdsubMerchantNo 查询用户的余额和积分信息。

适用对象
间连商户
请求 URL
https://openapi.shuhuipay.com/v1/user/query
请求方法
POST
ℹ️
接口说明:
  • 该接口用于查询指定用户的余额和积分
  • 通过公共参数 appIdsubMerchantNo 定位用户,无需额外业务参数
  • 返回的余额单位为元,精确到小数点后两位(数据库存储单位为分)

请求参数

ℹ️
无额外业务参数:

该接口无需在 bizContent 中传递额外参数,直接使用公共参数 appIdsubMerchantNo 进行查询。

请求示例

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;
}

注意事项

⚠️
权限限制:
  • 只能查询当前 appIdsubMerchantNo 对应用户的信息
  • 参数不匹配将返回 4003 错误码
  • 已禁用的用户无法查询,返回 4004 错误码
💡
查询说明:
  • 系统通过公共参数 appIdsubMerchantNo 定位用户
  • 余额返回单位为元,精确到小数点后两位(数据库存储单位为分)
  • 返回字段仅包含 money(余额)和 score(积分)
最佳实践:
  • 确保 appIdsubMerchantNo 参数正确,否则查询将失败
  • 敏感信息(如余额)请做好前端展示脱敏处理
  • 查询频率建议控制在合理范围内,避免频繁调用