🆕 #2719 【企业微信】增加家校沟通-基础接口

Author: 0katekate0

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

@@ -135,6 +135,70 @@ public interface WxCpSchoolUserService {
    */
   WxCpBaseResp deleteDepartment(Integer id) throws WxErrorException;
 
+  /**
+   * 设置关注「学校通知」的模式
+   * 可通过此接口修改家长关注「学校通知」的模式：“可扫码填写资料加入”或“禁止扫码填写资料加入”
+   * <p>
+   * 请求方式：POST（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/set_subscribe_mode?access_token=ACCESS_TOKEN
+   *
+   * @param subscribeMode 关注模式, 1:可扫码填写资料加入, 2:禁止扫码填写资料加入
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpBaseResp setSubscribeMode(@NonNull Integer subscribeMode) throws WxErrorException;
+
+  /**
+   * 获取关注「学校通知」的模式
+   * 可通过此接口获取家长关注「学校通知」的模式：“可扫码填写资料加入”或“禁止扫码填写资料加入”
+   * <p>
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_subscribe_mode?access_token=ACCESS_TOKEN
+   *
+   * @return
+   * @throws WxErrorException
+   */
+  Integer getSubscribeMode() throws WxErrorException;
+
+  /**
+   * 获取外部联系人详情
+   * 学校可通过此接口，根据外部联系人的userid（如何获取?），拉取外部联系人详情。
+   * <p>
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get?access_token=ACCESS_TOKEN&external_userid=EXTERNAL_USERID
+   *
+   * @param externalUserId 外部联系人的userid，注意不是学校成员的帐号
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpExternalContact getExternalContact(@NonNull String externalUserId) throws WxErrorException;
+
+  /**
+   * 获取可使用的家长范围
+   * 获取可在微信「学校通知-学校应用」使用该应用的家长范围，以学生或部门列表的形式返回。应用只能给该列表下的家长发送「学校通知」。注意该范围只能由学校的系统管理员在「管理端-家校沟通-配置」配置。
+   * <p>
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/school/agent/get_allow_scope?access_token=ACCESS_TOKEN&agentid=AGENTID
+   *
+   * @param agentId
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpAllowScope getAllowScope(@NonNull Integer agentId) throws WxErrorException;
+
+  /**
+   * 外部联系人openid转换
+   * 企业和服务商可通过此接口，将微信外部联系人的userid（如何获取?）转为微信openid，用于调用支付相关接口。暂不支持企业微信外部联系人（ExternalUserid为wo开头）的userid转openid。
+   * <p>
+   * 请求方式：POST（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/convert_to_openid?access_token=ACCESS_TOKEN
+   *
+   * @param externalUserId
+   * @return
+   * @throws WxErrorException
+   */
+  String convertToOpenId(@NonNull String externalUserId) throws WxErrorException;
+
   /**
    * 获取部门列表
    * 请求方式：GET（HTTPS）
@@ -146,6 +210,17 @@ public interface WxCpSchoolUserService {
    */
   WxCpDepartmentList listDepartment(Integer id) throws WxErrorException;
 
+  /**
+   * 获取「学校通知」二维码
+   * 学校可通过此接口获取「学校通知」二维码，家长可通过扫描此二维码关注「学校通知」并接收学校推送的消息。
+   * 请求方式：GET（HTTPS）
+   * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_subscribe_qr_code?access_token=ACCESS_TOKEN
+   *
+   * @return
+   * @throws WxErrorException
+   */
+  WxCpSubscribeQrCode getSubscribeQrCode() throws WxErrorException;
+
   /**
    * 修改自动升年级的配置
    * 请求方式： POST（HTTPS）

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

@@ -7,6 +7,7 @@
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.common.util.json.GsonParser;
 import me.chanjar.weixin.cp.api.WxCpSchoolUserService;
 import me.chanjar.weixin.cp.api.WxCpService;
 import me.chanjar.weixin.cp.bean.WxCpBaseResp;
@@ -15,6 +16,7 @@
 
 import java.util.List;
 
+import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.ExternalContact.*;
 import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.School.*;
 
 /**
@@ -125,13 +127,55 @@ public WxCpBaseResp deleteDepartment(Integer id) throws WxErrorException {
     return WxCpBaseResp.fromJson(responseContent);
   }
 
+  @Override
+  public WxCpBaseResp setSubscribeMode(@NonNull Integer subscribeMode) throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(SET_SUBSCRIBE_MODE);
+    JsonObject jsonObject = new JsonObject();
+    jsonObject.addProperty("subscribe_mode", subscribeMode);
+    String responseContent = this.cpService.post(apiUrl, jsonObject.toString());
+    return WxCpBaseResp.fromJson(responseContent);
+  }
+
+  @Override
+  public Integer getSubscribeMode() throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(GET_SUBSCRIBE_MODE);
+    String responseContent = this.cpService.get(apiUrl, null);
+    return GsonParser.parse(responseContent).get("subscribe_mode").getAsInt();
+  }
+
+  @Override
+  public WxCpExternalContact getExternalContact(@NonNull String externalUserId) throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(EXTERNAL_CONTACT_GET) + externalUserId;
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpExternalContact.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpAllowScope getAllowScope(@NonNull Integer agentId) throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(GET_ALLOW_SCOPE) + agentId;
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpAllowScope.fromJson(responseContent);
+  }
+
+  @Override
+  public String convertToOpenId(@NonNull String externalUserId) throws WxErrorException {
+    return cpService.getExternalContactService().convertToOpenid(externalUserId);
+  }
+
   @Override
   public WxCpDepartmentList listDepartment(Integer id) throws WxErrorException {
     String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(DEPARTMENT_LIST) + id;
     String responseContent = this.cpService.get(apiUrl, null);
     return WxCpDepartmentList.fromJson(responseContent);
   }
 
+  @Override
+  public WxCpSubscribeQrCode getSubscribeQrCode() throws WxErrorException {
+    String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(GET_SUBSCRIBE_QR_CODE);
+    String responseContent = this.cpService.get(apiUrl, null);
+    return WxCpSubscribeQrCode.fromJson(responseContent);
+  }
+
   @Override
   public WxCpSetUpgradeInfo setUpgradeInfo(Long upgradeTime, Integer upgradeSwitch) throws WxErrorException {
     String apiUrl = this.cpService.getWxCpConfigStorage().getApiUrl(SET_UPGRADE_INFO);

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/school/user/WxCpAllowScope.java

@@ -0,0 +1,62 @@
+package me.chanjar.weixin.cp.bean.school.user;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.Getter;
+import lombok.Setter;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 获取可使用的家长范围 返回结果.
+ *
+ * @author Wang_Wong
+ */
+@Data
+public class WxCpAllowScope extends WxCpBaseResp implements Serializable {
+  private static final long serialVersionUID = -5028321625140879571L;
+
+  @SerializedName("allow_scope")
+  private AllowScope allowScope;
+
+  @Setter
+  @Getter
+  public static class AllowScope implements Serializable {
+
+    @SerializedName("students")
+    private List<Student> students;
+
+    @SerializedName("departments")
+    private List<Integer> departments;
+
+    public static AllowScope fromJson(String json) {
+      return WxCpGsonBuilder.create().fromJson(json, AllowScope.class);
+    }
+
+    public String toJson() {
+      return WxCpGsonBuilder.create().toJson(this);
+    }
+
+  }
+
+  @Setter
+  @Getter
+  public static class Student implements Serializable {
+
+    @SerializedName("userid")
+    private String userId;
+
+  }
+
+  public static WxCpAllowScope fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpAllowScope.class);
+  }
+
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+}