在微信个人号二次开发中，搜索好友是很多业务场景的基础能力。比如通过微信号或手机号查找目标用户，然后获取添加好友所需的凭证信息。WTAPI 把这一能力封装成了标准的 HTTP 接口，下面记录一下实际调用过程。

接口地址

POST /finder/v2/api/contacts/search

请求参数

{
    "appId": "{{appid}}",
    "contactsInfo": "zhangch"
}

• appId：登录后获取的设备实例 ID。
• contactsInfo：要搜索的联系人信息，可以是微信号、手机号等。

对应的 curl 请求示例：

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://wx.chuapi.com/finder/v2/api/contacts/setFriendPermissions")
   .header("X-finder-TOKEN", "")
   .header("Authorization", "Bearer eyJhbGciOiJIUzUxMiJ9.eyJsb2dpbl91c2VyX2tleSI6IjAxNmM2ZDQ5LWIxNWMtNGRjMy05YzQzLWZmYzZmNDhhMTg3MyJ9.1JWq9ntjam20_XDlSbklWTxbV-vg-F_dY1LYVX05BndRAuaJbv3iSwoDY-BuMwe1sdKxDXtDTMWJgXNMff4nOg")
   .header("Content-Type", "application/json")
   .body("{\n    \"appId\": \"{{appid}}\",\n    \"wxid\": \"wxid_br88xhuif7k322\",\n    \"onlyChat\": true\n}")
   .asString();

返回结果解析

接口返回结构如下：

{
    "ret": 200,
    "msg": "操作成功",
    "data": {
        "v3": "v3_020b3826fd030100000000006c20217514f7f2...",
        "nickName": "zhang",
        "sex": 1,
        "signature": "学习、成长、锻炼",
        "bigHeadImgUrl": "http://wx.qlogo.cn/.../0",
        "smallHeadImgUrl": "http://wx.qlogo.cn/.../132",
        "v4": "v4_000b708f0b04000001000000000056d3690365e0..."
    }
}

重点字段说明：

• v3：搜索好友的凭证。如果该联系人已经是好友，这里会返回对方的 wxid；如果不是好友，则返回 stranger 类型的凭证，用于添加好友。
• v4：添加好友请求时需要的附加凭证。
• nickName、sex、signature、bigHeadImgUrl、smallHeadImgUrl：基础资料，可用于本地数据补全。

开发注意事项

1. 凭证复用：v3 和 v4 获取后可以在一定时间内复用，建议缓存到本地，避免重复搜索。
2. 频率控制：搜索接口不宜高频调用，否则容易触发风控。实际项目中建议加限流和重试机制。
3. 异常处理：如果联系人不存在、对方关闭搜索，或当前账号被限制，接口会返回相应错误码，需要在前端做好兼容。
4. 与添加好友链路衔接：拿到 v3/v4 后，下一步通常是调用添加好友接口完成请求发送。

小结

搜索好友接口虽然简单，但它是好友关系链路的第一环。理解 v3 和 v4 的含义、掌握返回结构，并做好缓存和风控策略，后续添加好友、好友资料同步等功能会顺利很多。