🆕 【企业微信】添加获客助手api

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

@@ -4,6 +4,7 @@
 import me.chanjar.weixin.common.error.WxErrorException;
 import me.chanjar.weixin.cp.bean.WxCpBaseResp;
 import me.chanjar.weixin.cp.bean.external.*;
+import me.chanjar.weixin.cp.bean.external.acquisition.*;
 import me.chanjar.weixin.cp.bean.external.contact.*;
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRule;
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleAddRequest;
@@ -1144,4 +1145,117 @@ WxMediaUploadResult uploadAttachment(String mediaType, Integer attachmentType, F
    */
   void deleteProductAlbum(String productId) throws WxErrorException;
 
+  /**
+   * <pre>
+   * 获取获客链接列表
+   * 企业可通过此接口获取当前仍然有效的获客链接。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/list_link?access_token=ACCESS_TOKEN">接口地址</a>
+   *
+   * <a href="https://developer.work.weixin.qq.com/document/path/97297#%E8%8E%B7%E5%8F%96%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5%E5%88%97%E8%A1%A8">文档地址</a>
+   * </pre>
+   * @param limit 商品id
+   * @param cursor 商品id
+   * @return 获客链接列表
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCustomerAcquisitionList customerAcquisitionLinkList(Integer limit, String cursor) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 获取获客链接详情
+   * 企业可通过此接口根据获客链接id获取链接配置详情。。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/get?access_token=ACCESS_TOKEN">接口地址</a>
+   *
+   * <a href="https://developer.work.weixin.qq.com/document/path/97297#%E8%8E%B7%E5%8F%96%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5%E8%AF%A6%E6%83%85">文档地址</a>
+   * </pre>
+   * @param linkId 获客链接ID
+   * @return 获客链接详情
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCustomerAcquisitionInfo customerAcquisitionLinkGet(String linkId) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 创建获客链接
+   * 企业可通过此接口创建新的获客链接。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/create_link?access_token=ACCESS_TOKEN">接口地址</a>
+   * <a href="https://developer.work.weixin.qq.com/document/path/97297#%E5%88%9B%E5%BB%BA%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5">文档地址</a>
+   * </pre>
+   *
+   * @param wxCpCustomerAcquisitionRequest 创建链接请求
+   * @return 创建链接详情
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCustomerAcquisitionCreateResult customerAcquisitionLinkCreate(WxCpCustomerAcquisitionRequest wxCpCustomerAcquisitionRequest) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 编辑获客链接
+   * 企业可通过此接口编辑获客链接，修改获客链接的关联范围或修改获客链接的名称。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/update_link?access_token=ACCESS_TOKEN">接口地址</a>
+   * <a href="https://developer.work.weixin.qq.com/document/path/97297#%E7%BC%96%E8%BE%91%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5">文档地址</a>
+   * </pre>
+   *
+   * @param wxCpCustomerAcquisitionRequest 编辑链接请求
+   * @return 编辑链接详情
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpBaseResp customerAcquisitionUpdate(WxCpCustomerAcquisitionRequest wxCpCustomerAcquisitionRequest) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 删除获客链接
+   * 企业可通过此接口删除获客链接，删除后的获客链接将无法继续使用。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/delete_link?access_token=ACCESS_TOKEN">接口地址</a>
+   * <a href="https://developer.work.weixin.qq.com/document/path/97297#%E5%88%A0%E9%99%A4%E8%8E%B7%E5%AE%A2%E9%93%BE%E6%8E%A5">文档地址</a>
+   * </pre>
+   *
+   * @param linkId 获客链接的id
+   * @return 删除结果
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpBaseResp customerAcquisitionLinkDelete(String linkId) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 获取获客客户列表
+   * 企业可通过此接口获取到由指定的获客链接添加的客户列表。
+   * 请求方式：POST(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition/customer?access_token=ACCESS_TOKEN">接口地址</a>
+   * <a href="https://developer.work.weixin.qq.com/document/path/97298">文档地址</a>
+   * </pre>
+   *
+   * @param linkId 获客链接id
+   * @param limit  返回的最大记录数，整型，最大值1000
+   * @param cursor 用于分页查询的游标，字符串类型，由上一次调用返回，首次调用可不填
+   * @return 由获客链接添加的客户信息列表
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCustomerAcquisitionCustomerList customerAcquisitionCustomer(String linkId, Integer limit, String cursor) throws WxErrorException;
+
+  /**
+   * <pre>
+   * 查询剩余使用量
+   * 企业可通过此接口查询当前剩余的使用量。
+   * 请求方式：GET(HTTPS)
+   * 请求地址：
+   * <a href="https://qyapi.weixin.qq.com/cgi-bin/externalcontact/customer_acquisition_quota?access_token=ACCESS_TOKEN">接口地址</a>
+   * <a href="https://developer.work.weixin.qq.com/document/path/97375">文档地址</a>
+   * </pre>
+   *
+   * @return 剩余使用量
+   * @throws WxErrorException the wx error exception
+   */
+  WxCpCustomerAcquisitionQuota customerAcquisitionQuota() throws WxErrorException;
 }

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

@@ -16,6 +16,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.acquisition.*;
 import me.chanjar.weixin.cp.bean.external.contact.*;
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRule;
 import me.chanjar.weixin.cp.bean.external.interceptrule.WxCpInterceptRuleAddRequest;
@@ -741,6 +742,63 @@ public void deleteProductAlbum(String productId) throws WxErrorException {
     this.mainService.post(url, o.toString());
   }
 
+  @Override
+  public WxCpCustomerAcquisitionList customerAcquisitionLinkList(Integer limit, String cursor) throws WxErrorException {
+    JsonObject o = new JsonObject();
+    o.addProperty("limit", limit);
+    o.addProperty("cursor", cursor);
+
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_LINK_LIST);
+    return WxCpCustomerAcquisitionList.fromJson(this.mainService.post(url, o));
+  }
+
+  @Override
+  public WxCpCustomerAcquisitionInfo customerAcquisitionLinkGet(String linkId) throws WxErrorException {
+    JsonObject o = new JsonObject();
+    o.addProperty("link_id", linkId);
+
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_LINK_GET);
+    return WxCpCustomerAcquisitionInfo.fromJson(this.mainService.post(url, o));
+  }
+
+  @Override
+  public WxCpCustomerAcquisitionCreateResult customerAcquisitionLinkCreate(WxCpCustomerAcquisitionRequest wxCpCustomerAcquisitionRequest) throws WxErrorException {
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_LINK_CREATE);
+    return WxCpCustomerAcquisitionCreateResult.fromJson(this.mainService.post(url, wxCpCustomerAcquisitionRequest.toJson()));
+  }
+
+  @Override
+  public WxCpBaseResp customerAcquisitionUpdate(WxCpCustomerAcquisitionRequest wxCpCustomerAcquisitionRequest) throws WxErrorException {
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_LINK_UPDATE);
+    return WxCpBaseResp.fromJson(this.mainService.post(url, wxCpCustomerAcquisitionRequest.toJson()));
+  }
+
+  @Override
+  public WxCpBaseResp customerAcquisitionLinkDelete(String linkId) throws WxErrorException {
+    JsonObject o = new JsonObject();
+    o.addProperty("link_id", linkId);
+
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_LINK_DELETE);
+    return WxCpBaseResp.fromJson(this.mainService.post(url, o));
+  }
+
+  @Override
+  public WxCpCustomerAcquisitionCustomerList customerAcquisitionCustomer(String linkId, Integer limit, String cursor) throws WxErrorException {
+    JsonObject o = new JsonObject();
+    o.addProperty("link_id", linkId);
+    o.addProperty("limit", limit);
+    o.addProperty("cursor", cursor);
+
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_CUSTOMER);
+    return WxCpCustomerAcquisitionCustomerList.fromJson(this.mainService.post(url, o));
+  }
+
+  @Override
+  public WxCpCustomerAcquisitionQuota customerAcquisitionQuota() throws WxErrorException {
+    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_QUOTA);
+    return WxCpCustomerAcquisitionQuota.fromJson(this.mainService.get(url, null));
+  }
+
   @Override
   public WxCpGroupJoinWayResult addJoinWay(WxCpGroupJoinWayInfo wxCpGroupJoinWayInfo) throws WxErrorException {
     if (wxCpGroupJoinWayInfo.getJoinWay().getChatIdList() != null && wxCpGroupJoinWayInfo.getJoinWay().getChatIdList().size() > 5) {

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/external/acquisition/WxCpCustomerAcquisitionCreateResult.java

@@ -0,0 +1,23 @@
+package me.chanjar.weixin.cp.bean.external.acquisition;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+/**
+ * 创建获客助手链接结果
+ *
+ * @author alien_zyl
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class WxCpCustomerAcquisitionCreateResult extends WxCpBaseResp {
+  private static final long serialVersionUID = -6301164294371861558L;
+
+  private WxCpCustomerAcquisitionInfo.Link link;
+
+  public static WxCpCustomerAcquisitionCreateResult fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpCustomerAcquisitionCreateResult.class);
+  }
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/external/acquisition/WxCpCustomerAcquisitionCustomerList.java

@@ -0,0 +1,68 @@
+package me.chanjar.weixin.cp.bean.external.acquisition;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 获取由获客链接添加的客户信息结果
+ *
+ * @author alien_zyl
+ */
+@Data
+public class WxCpCustomerAcquisitionCustomerList {
+
+  @SerializedName("customer_list")
+  private List<Customer> customerList;
+
+  /**
+   * 分页游标，再下次请求时填写以获取之后分页的记录，如果已经没有更多的数据则返回空
+   */
+  @SerializedName("next_cursor")
+  private String nextCursor;
+
+
+  public static WxCpCustomerAcquisitionCustomerList fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpCustomerAcquisitionCustomerList.class);
+  }
+
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+  @Data
+  public static class Customer implements Serializable {
+    private static final long serialVersionUID = 4456053823277371278L;
+
+    /**
+     * 客户external_userid
+     */
+    @SerializedName("external_userid")
+    private String externalUserid;
+
+    /**
+     * 通过获客链接添加此客户的跟进人userid
+     */
+    @SerializedName("userid")
+    private String userid;
+
+    /**
+     * 会话状态，0-客户未发消息 1-客户已发送消息
+     */
+    @SerializedName("chat_status")
+    private Integer chatStatus;
+
+    /**
+     * 用于区分客户具体是通过哪个获客链接进行添加，
+     * 用户可在获客链接后拼接customer_channel=自定义字符串，字符串不超过64字节，超过会被截断。
+     * 通过点击带有customer_channel参数的链接获取到的客户，调用获客信息接口或获取客户详情接口时，返回的state参数即为链接后拼接自定义字符串
+     */
+    @SerializedName("state")
+    private String state;
+
+  }
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/external/acquisition/WxCpCustomerAcquisitionInfo.java

@@ -0,0 +1,103 @@
+package me.chanjar.weixin.cp.bean.external.acquisition;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 获客链接详情
+ *
+ * @author alien_zyl
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class WxCpCustomerAcquisitionInfo extends WxCpBaseResp implements Serializable {
+
+  private static final long serialVersionUID = -425354507473041229L;
+  /**
+   * link_id列表
+   */
+  @SerializedName("link")
+  private Link link;
+
+  /**
+   * 分页游标，在下次请求时填写以获取之后分页的记录
+   */
+  @SerializedName("range")
+  private Range range;
+
+  /**
+   * 是否无需验证，默认为true
+   */
+  @SerializedName("skip_verify")
+  private Boolean skipVerify;
+
+  public static WxCpCustomerAcquisitionInfo fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpCustomerAcquisitionInfo.class);
+  }
+
+  @Data
+  @EqualsAndHashCode(callSuper = true)
+  public static class Link extends WxCpBaseResp implements Serializable {
+    private static final long serialVersionUID = 6750537220943228300L;
+
+    /**
+     * 获客链接的id
+     */
+    @SerializedName("link_id")
+    private String linkId;
+
+    /**
+     * 获客链接的名称
+     */
+    @SerializedName("link_name")
+    private String linkName;
+
+    /**
+     * 获客链接实际的url
+     */
+    @SerializedName("url")
+    private String url;
+
+    /**
+     * 创建时间
+     */
+    @SerializedName("create_time")
+    private Long createTime;
+
+    public static Link fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Link.class);
+    }
+  }
+
+  @Data
+  public static class Range implements Serializable {
+    private static final long serialVersionUID = -6343768645371744643L;
+
+    /**
+     * 此获客链接关联的userid列表，最多可关联100个
+     */
+    @SerializedName("user_list")
+    private List<String> userList;
+
+    /**
+     * 此获客链接关联的部门id列表，部门覆盖总人数最多100个
+     */
+    @SerializedName("department_list")
+    private List<String> departmentList;
+
+    public static Range fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, Range.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+  }
+
+}