🆕 #3405 【企业微信】增加获取已服务的外部联系人的接口

Co-authored-by: zhanyan <zhanyan.work@outlook.com>

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

@@ -1,5 +1,10 @@
 package me.chanjar.weixin.cp.api;
 
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Date;
+import java.util.List;
 import me.chanjar.weixin.common.bean.result.WxMediaUploadResult;
 import me.chanjar.weixin.common.error.WxErrorException;
 import me.chanjar.weixin.cp.bean.WxCpBaseResp;
@@ -11,12 +16,6 @@ import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleAddRequ
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleInfo;
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleList;
 
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.Date;
-import java.util.List;
-
 /**
  * <pre>
  * 外部联系人管理接口，企业微信的外部联系人的接口和通讯录接口已经拆离
@@ -381,6 +380,24 @@ public interface WxCpExternalContactService {
                                                      Integer limit)
     throws WxErrorException;
 
+  /**
+   * 获取已服务的外部联系人
+   * <pre>
+   *  企业可通过此接口获取所有已服务的外部联系人，及其添加人和加入的群聊。
+   * 外部联系人分为客户和其他外部联系人，如果是客户，接口将返回外部联系人临时ID和externaluserid；如果是其他外部联系人，接口将只返回外部联系人临时ID。
+   * 请求方式：POST（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/contact_list?access_token=ACCESS_TOKEN
+   * 文档地址: https://developer.work.weixin.qq.com/document/path/99434
+   * </pre>
+   *
+   * @param cursor     the cursor
+   * @param limit      the  limit
+   * @return 已服务的外部联系人列表
+   * @throws WxErrorException .
+   * @apiNote 企业可通过外部联系人临时ID排除重复数据，外部联系人临时ID有效期为4小时。
+   */
+  WxCpExternalContactListInfo getContactList(String cursor, Integer limit) throws WxErrorException;
+
   /**
    * 修改客户备注信息.
    * <pre>

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

@@ -1,7 +1,16 @@
 package me.chanjar.weixin.cp.api.impl;
 
+import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.ExternalContact.*;
+
 import com.google.gson.Gson;
 import com.google.gson.JsonObject;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
+import java.util.UUID;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 import me.chanjar.weixin.common.bean.result.WxMediaUploadResult;
@@ -26,16 +35,6 @@ import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleList;
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
 
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.Collections;
-import java.util.Date;
-import java.util.List;
-import java.util.UUID;
-
-import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.ExternalContact.*;
-
 /**
  * The type Wx cp external contact service.
  *
@@ -215,6 +214,20 @@ public class WxCpExternalContactServiceImpl implements WxCpExternalContactServic
     return WxCpExternalContactBatchInfo.fromJson(responseContent);
   }
 
+  @Override
+  public WxCpExternalContactListInfo getContactList(String cursor, Integer limit) throws WxErrorException {
+    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(GET_CONTACT_LIST);
+    JsonObject json = new JsonObject();
+    if (StringUtils.isNotBlank(cursor)) {
+      json.addProperty("cursor", cursor);
+    }
+    if (limit != null) {
+      json.addProperty("limit", limit);
+    }
+    String responseContent = this.mainService.post(url, json.toString());
+    return WxCpExternalContactListInfo.fromJson(responseContent);
+  }
+
   @Override
   public void updateRemark(WxCpUpdateRemarkRequest request) throws WxErrorException {
     final String url = this.mainService.getWxCpConfigStorage().getApiUrl(UPDATE_REMARK);

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/external/contact/WxCpExternalContactListInfo.java

@@ -0,0 +1,92 @@
+package me.chanjar.weixin.cp.bean.external.contact;
+
+import com.google.gson.annotations.SerializedName;
+import java.io.Serializable;
+import java.util.List;
+import lombok.Getter;
+import lombok.Setter;
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+/**
+ *   获取已服务的外部联系人( <a href="https://developer.work.weixin.qq.com/document/path/99434">参考文档</a>)
+ * @see WxCpService#getExternalContactService()
+ * @serial
+ */
+@Getter
+@Setter
+public class WxCpExternalContactListInfo implements Serializable {
+
+  private static final long serialVersionUID = 7114885886548364396L;
+
+  @SerializedName("next_cursor")
+  private String nextCursor;
+
+  @SerializedName("errcode")
+  private String errcode;
+
+  @SerializedName("errmsg")
+  private String errmsg;
+
+  @SerializedName("info_list")
+  private List<ExternalContactInfo> infoList;
+
+  @Getter
+  @Setter
+  public static class ExternalContactInfo implements Serializable{
+
+    private static final long serialVersionUID = -7400291089462740100L;
+
+    /**
+     * 是否被成员标记为客户
+     */
+    @SerializedName("is_customer")
+    private Boolean isCustomer;
+
+    /**
+     * 外部联系人临时ID
+     */
+    @SerializedName("tmp_openid")
+    private String tmpOpenid;
+
+    /**
+     * 外部联系人的externaluserid（如果是客户才返回）
+     */
+    @SerializedName("external_userid")
+    private String externalUserid;
+
+    /**
+     * 脱敏后的外部联系人昵称（如果是其他外部联系人才返回）
+     */
+    @SerializedName("name")
+    private String name;
+
+    /**
+     * 添加此外部联系人的企业成员或外部联系人所在群聊的群主userid
+     */
+    @SerializedName("follow_userid")
+    private String followUserid;
+
+    /**
+     * 外部联系人所在的群聊ID（如果群聊被成员标记为客户群才返回）
+     */
+    @SerializedName("chat_id")
+    private String chatId;
+
+    /**
+     * 外部联系人所在群聊的群名（如果群聊未被成员标记为客户群才返回）
+     */
+    @SerializedName("chat_name")
+    private String chatName;
+
+    /**
+     * 外部联系人首次添加/进群的时间
+     */
+    @SerializedName("add_time")
+    private Long addTime;
+  }
+  public static WxCpExternalContactListInfo fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpExternalContactListInfo.class);
+  }
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/constant/WxCpApiPathConsts.java

@@ -1137,6 +1137,9 @@ public interface WxCpApiPathConsts {
      * The constant GET_CONTACT_DETAIL_BATCH.
      */
     String GET_CONTACT_DETAIL_BATCH = "/cgi-bin/externalcontact/batch/get_by_user?";
+
+    String GET_CONTACT_LIST = "/cgi-bin/externalcontact/contact_list?";
+
     /**
      * The constant UPDATE_REMARK.
      */

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

@@ -1,7 +1,13 @@
 package me.chanjar.weixin.cp.api.impl;
 
+import static org.testng.Assert.assertNotNull;
+
 import com.google.common.collect.Lists;
 import com.google.inject.Inject;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
 import me.chanjar.weixin.common.error.WxErrorException;
 import me.chanjar.weixin.common.util.XmlUtils;
 import me.chanjar.weixin.cp.api.ApiTestModule;
@@ -10,6 +16,7 @@ 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.contact.WxCpExternalContactListInfo;
 import me.chanjar.weixin.cp.bean.external.msg.Attachment;
 import me.chanjar.weixin.cp.bean.external.msg.AttachmentBuilder;
 import me.chanjar.weixin.cp.bean.external.msg.Image;
@@ -22,13 +29,6 @@ import org.testng.annotations.Guice;
 import org.testng.annotations.Test;
 import org.testng.collections.CollectionUtils;
 
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.Date;
-import java.util.List;
-
-import static org.testng.Assert.assertNotNull;
-
 /**
  * The type Wx cp external contact service impl test.
  */
@@ -188,6 +188,19 @@ public class WxCpExternalContactServiceImplTest {
     assertNotNull(result);
   }
 
+  /**
+   * Test get contact list.
+   *
+   * @throws WxErrorException the wx error exception
+   */
+  @Test
+  public void testGetContactList() throws WxErrorException {
+    WxCpExternalContactListInfo result =
+      this.wxCpService.getExternalContactService().getContactList("", 100);
+    System.out.println(result);
+    assertNotNull(result);
+  }
+
   /**
    * Test get corp tag list.
    *