🎨 #2295 【企业微信】批量获取外部客户详情接口支持多个userId

Author: watertreestar

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpExternalContactService.java

@@ -153,6 +153,7 @@ public interface WxCpExternalContactService {
 
   /**
    * 企业和服务商可通过此接口，将微信外部联系人的userid转为微信openid，用于调用支付相关接口。暂不支持企业微信外部联系人（ExternalUserid为wo开头）的userid转openid。
+   *
    * @param externalUserid 微信外部联系人的userid
    * @return 该企业的外部联系人openid
    * @throws WxErrorException .
@@ -197,13 +198,13 @@ public interface WxCpExternalContactService {
    * 第三方/自建应用调用时，返回的跟进人follow_user仅包含应用可见范围之内的成员。
    * </pre>
    *
-   * @param userId 企业成员的userid，注意不是外部联系人的帐号
-   * @param cursor the cursor
-   * @param limit the  limit
+   * @param userIdList 企业成员的userid列表，注意不是外部联系人的帐号
+   * @param cursor     the cursor
+   * @param limit      the  limit
    * @return wx cp user external contact batch info
    * @throws WxErrorException .
    */
-  WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
+  WxCpExternalContactBatchInfo getContactDetailBatch(String[] userIdList, String cursor,
                                                      Integer limit)
     throws WxErrorException;
 
@@ -273,24 +274,25 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
    * @param takeOverUserid the take over userid
    * @return wx cp base resp
    * @throws WxErrorException the wx error exception
-   * @deprecated 此后续将不再更新维护,建议使用 {@link #transferCustomer(WxCpUserTransferCustomerReq)}
+   * @deprecated 此后续将不再更新维护, 建议使用 {@link #transferCustomer(WxCpUserTransferCustomerReq)}
    */
   @Deprecated
   WxCpBaseResp transferExternalContact(String externalUserid, String handOverUserid, String takeOverUserid) throws WxErrorException;
 
   /**
    * 企业可通过此接口，转接在职成员的客户给其他成员。
-   *  <per>
+   * <per>
    * external_userid必须是handover_userid的客户（即配置了客户联系功能的成员所添加的联系人）。
    * 在职成员的每位客户最多被分配2次。客户被转接成功后，将有90个自然日的服务关系保护期，保护期内的客户无法再次被分配。
-   *
+   * <p>
    * 权限说明：
-   *   * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
+   * * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
    * 第三方应用需拥有“企业客户权限->客户联系->在职继承”权限
    * 接替成员必须在此第三方应用或自建应用的可见范围内。
    * 接替成员需要配置了客户联系功能。
    * 接替成员需要在企业微信激活且已经过实名认证。
-   *  </per>
+   * </per>
+   *
    * @param req 转接在职成员的客户给其他成员请求实体
    * @return wx cp base resp
    * @throws WxErrorException the wx error exception
@@ -300,35 +302,37 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
   /**
    * 企业和第三方可通过此接口查询在职成员的客户转接情况。
    * <per>
-   *   权限说明：
-   *
+   * 权限说明：
+   * <p>
    * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
    * 第三方应用需拥有“企业客户权限->客户联系->在职继承”权限
    * 接替成员必须在此第三方应用或自建应用的可见范围内。
    * </per>
+   *
    * @param handOverUserid 原添加成员的userid
    * @param takeOverUserid 接替成员的userid
-   * @param cursor 分页查询的cursor，每个分页返回的数据不会超过1000条；不填或为空表示获取第一个分页；
+   * @param cursor         分页查询的cursor，每个分页返回的数据不会超过1000条；不填或为空表示获取第一个分页；
    * @return 客户转接接口实体
    * @throws WxErrorException the wx error exception
    */
-  WxCpUserTransferResultResp transferResult(@NotNull String handOverUserid, @NotNull String takeOverUserid, String cursor)  throws WxErrorException;
+  WxCpUserTransferResultResp transferResult(@NotNull String handOverUserid, @NotNull String takeOverUserid, String cursor) throws WxErrorException;
 
   /**
    * 企业可通过此接口，分配离职成员的客户给其他成员。
-   *  <per>
+   * <per>
    * handover_userid必须是已离职用户。
    * external_userid必须是handover_userid的客户（即配置了客户联系功能的成员所添加的联系人）。
    * 在职成员的每位客户最多被分配2次。客户被转接成功后，将有90个自然日的服务关系保护期，保护期内的客户无法再次被分配。
-   *
+   * <p>
    * 权限说明：
-   *
+   * <p>
    * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
    * 第三方应用需拥有“企业客户权限->客户联系->离职分配”权限
    * 接替成员必须在此第三方应用或自建应用的可见范围内。
    * 接替成员需要配置了客户联系功能。
    * 接替成员需要在企业微信激活且已经过实名认证。
-   *  </per>
+   * </per>
+   *
    * @param req 转接在职成员的客户给其他成员请求实体
    * @return wx cp base resp
    * @throws WxErrorException the wx error exception
@@ -339,18 +343,19 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
    * 企业和第三方可通过此接口查询离职成员的客户分配情况。
    * <per>
    * 权限说明：
-   *
+   * <p>
    * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
    * 第三方应用需拥有“企业客户权限->客户联系->在职继承”权限
    * 接替成员必须在此第三方应用或自建应用的可见范围内。
    * </per>
+   *
    * @param handOverUserid 原添加成员的userid
    * @param takeOverUserid 接替成员的userid
-   * @param cursor 分页查询的cursor，每个分页返回的数据不会超过1000条；不填或为空表示获取第一个分页；
+   * @param cursor         分页查询的cursor，每个分页返回的数据不会超过1000条；不填或为空表示获取第一个分页；
    * @return 客户转接接口实体
    * @throws WxErrorException the wx error exception
    */
-  WxCpUserTransferResultResp resignedTransferResult(@NotNull String handOverUserid, @NotNull String takeOverUserid, String cursor)  throws WxErrorException;
+  WxCpUserTransferResultResp resignedTransferResult(@NotNull String handOverUserid, @NotNull String takeOverUserid, String cursor) throws WxErrorException;
 
   /**
    * <pre>
@@ -360,14 +365,14 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
    * 微信文档：https://work.weixin.qq.com/api/doc/90000/90135/92119
    * </pre>
    *
-   * @deprecated 请使用 {@link WxCpExternalContactService#listGroupChat(Integer, String, int, String[])}
    * @param pageIndex the page index
    * @param pageSize  the page size
    * @param status    the status
    * @param userIds   the user ids
    * @param partyIds  the party ids
    * @return the wx cp user external group chat list
    * @throws WxErrorException the wx error exception
+   * @deprecated 请使用 {@link WxCpExternalContactService#listGroupChat(Integer, String, int, String[])}
    */
   @Deprecated
   WxCpUserExternalGroupChatList listGroupChat(Integer pageIndex, Integer pageSize, int status, String[] userIds, String[] partyIds) throws WxErrorException;
@@ -380,10 +385,10 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
    * 微信文档：https://work.weixin.qq.com/api/doc/90000/90135/92119
    * </pre>
    *
-   * @param limit     分页，预期请求的数据量，取值范围 1 ~ 1000
-   * @param cursor    用于分页查询的游标，字符串类型，由上一次调用返回，首次调用不填
-   * @param status    客户群跟进状态过滤。0 - 所有列表(即不过滤)  1 - 离职待继承  2 - 离职继承中  3 - 离职继承完成 默认为0
-   * @param userIds   群主过滤。如果不填，表示获取应用可见范围内全部群主的数据（但是不建议这么用，如果可见范围人数超过1000人，为了防止数据包过大，会报错 81017）;用户ID列表。最多100个
+   * @param limit   分页，预期请求的数据量，取值范围 1 ~ 1000
+   * @param cursor  用于分页查询的游标，字符串类型，由上一次调用返回，首次调用不填
+   * @param status  客户群跟进状态过滤。0 - 所有列表(即不过滤)  1 - 离职待继承  2 - 离职继承中  3 - 离职继承完成 默认为0
+   * @param userIds 群主过滤。如果不填，表示获取应用可见范围内全部群主的数据（但是不建议这么用，如果可见范围人数超过1000人，为了防止数据包过大，会报错 81017）;用户ID列表。最多100个
    * @return the wx cp user external group chat list
    * @throws WxErrorException the wx error exception
    */
@@ -404,30 +409,30 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
   WxCpUserExternalGroupChatInfo getGroupChat(String chatId, Integer needName) throws WxErrorException;
 
   /**
-   *
    * 企业可通过此接口，将已离职成员为群主的群，分配给另一个客服成员。
    *
    * <per>
    * 注意：：
-   *
+   * <p>
    * 群主离职了的客户群，才可继承
    * 继承给的新群主，必须是配置了客户联系功能的成员
    * 继承给的新群主，必须有设置实名
    * 继承给的新群主，必须有激活企业微信
    * 同一个人的群，限制每天最多分配300个给新群主
-   *
+   * <p>
    * 权限说明:
-   *
+   * <p>
    * 企业需要使用“客户联系”secret或配置到“可调用应用”列表中的自建应用secret所获取的accesstoken来调用（accesstoken如何获取？）。
    * 第三方应用需拥有“企业客户权限->客户联系->分配离职成员的客户群”权限
    * 对于第三方/自建应用，群主必须在应用的可见范围。
    * </per>
-   * @param chatIds 需要转群主的客户群ID列表。取值范围： 1 ~ 100
-   * @param newOwner  新群主ID
+   *
+   * @param chatIds  需要转群主的客户群ID列表。取值范围： 1 ~ 100
+   * @param newOwner 新群主ID
    * @return 分配结果，主要是分配失败的群列表
-   * @throws WxErrorException  the wx error exception
+   * @throws WxErrorException the wx error exception
    */
-  WxCpUserExternalGroupChatTransferResp transferGroupChat(String[] chatIds, String newOwner)  throws WxErrorException;
+  WxCpUserExternalGroupChatTransferResp transferGroupChat(String[] chatIds, String newOwner) throws WxErrorException;
 
   /**
    * <pre>
@@ -520,7 +525,7 @@ WxCpExternalContactBatchInfo getContactDetailBatch(String userId, String cursor,
    * 同时传递tag_id和group_id时，忽略tag_id，仅以group_id作为过滤条件。
    * </pre>
    *
-   * @param tagId the tag id
+   * @param tagId   the tag id
    * @param groupId the tagGroup id
    * @return corp tag list
    * @throws WxErrorException the wx error exception

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpExternalContactServiceImpl.java

@@ -148,7 +148,7 @@ public String unionidToExternalUserid(@NotNull String unionid) throws WxErrorExc
   }
 
   @Override
-  public WxCpExternalContactBatchInfo getContactDetailBatch(String userId,
+  public WxCpExternalContactBatchInfo getContactDetailBatch(String[] userIdList,
                                                             String cursor,
                                                             Integer limit)
     throws WxErrorException {
@@ -157,7 +157,7 @@ public WxCpExternalContactBatchInfo getContactDetailBatch(String userId,
         .getWxCpConfigStorage()
         .getApiUrl(GET_CONTACT_DETAIL_BATCH);
     JsonObject json = new JsonObject();
-    json.addProperty("userid", userId);
+    json.add("userid_list", new Gson().toJsonTree(userIdList).getAsJsonArray());
     if (StringUtils.isNotBlank(cursor)) {
       json.addProperty("cursor", cursor);
     }

weixin-java-cp/src/test/java/me/chanjar/weixin/cp/api/impl/WxCpExternalContactServiceImplTest.java

@@ -7,6 +7,7 @@
 import me.chanjar.weixin.cp.api.WxCpService;
 import me.chanjar.weixin.cp.bean.WxCpBaseResp;
 import me.chanjar.weixin.cp.bean.external.*;
+import me.chanjar.weixin.cp.bean.external.contact.WxCpExternalContactBatchInfo;
 import me.chanjar.weixin.cp.bean.external.contact.WxCpExternalContactInfo;
 import me.chanjar.weixin.cp.bean.external.msg.Attachment;
 import me.chanjar.weixin.cp.bean.external.msg.Image;
@@ -115,6 +116,14 @@ public void testGetContactDetail() throws WxErrorException {
     assertNotNull(result);
   }
 
+  @Test
+  public void testGetContactDetailBatch() throws WxErrorException {
+    String userId = this.configStorage.getUserId();
+    WxCpExternalContactBatchInfo result = this.wxCpService.getExternalContactService().getContactDetailBatch(new String[]{userId}, "", 100);
+    System.out.println(result);
+    assertNotNull(result);
+  }
+
   @Test
   public void testGetCorpTagList() throws WxErrorException {
     String[] tag = {};
@@ -236,14 +245,14 @@ public void testresignedTrnsferResult() throws WxErrorException {
 
   @Test
   public void testListGroupChat() throws WxErrorException {
-    WxCpUserExternalGroupChatList result = this.wxCpService.getExternalContactService().listGroupChat(0, 100 ,0,new String[1],new String[1]);
+    WxCpUserExternalGroupChatList result = this.wxCpService.getExternalContactService().listGroupChat(0, 100, 0, new String[1], new String[1]);
     System.out.println(result);
     assertNotNull(result);
   }
 
   @Test
   public void testListGroupChatV3() throws WxErrorException {
-    WxCpUserExternalGroupChatList result = this.wxCpService.getExternalContactService().listGroupChat(100, "" ,0,new String[1]);
+    WxCpUserExternalGroupChatList result = this.wxCpService.getExternalContactService().listGroupChat(100, "", 0, new String[1]);
     System.out.println(result);
     assertNotNull(result);
   }
@@ -301,7 +310,7 @@ public void testUpdateRemark() throws WxErrorException {
       .externalUserId("aaa")
       .remark("aa")
       .remarkCompany("aaa")
-      .remarkMobiles(new String[]{"111","222"})
+      .remarkMobiles(new String[]{"111", "222"})
       .remarkPicMediaId("aaa")
       .build());
   }