微信企業號開發-如何建立連接

連接將使你的企業號更具價值，你可以使用以下三種方式，連接你的企業號及企業應用：

1、企業應用調用企業號提供的接口，管理或查詢企業號后台所管理的資源、或給成員發送消息等，以下稱主動調用模式。

2、企業號把用戶發送的消息或用戶觸發的事件推送給企業應用，由企業應用處理，以下稱回調模式。

3、用戶在微信中閱讀企業應用下發的H5頁面，該頁面可以調用微信提供的原生接口，使用微信開放的終端能力，以下稱JSAPI模式。

通過這三種連接方式的結合，你可以在企業號中建立功能強大的移動輕應用，並依托微信數億活躍用戶，幫助企業方便、快捷地實現應用的部署，並確保應用的活躍度。

一、主動調用

1、簡述

主動調用是最基本的連接模式，當你的應用調用企業號時，需使用https協議、Json數據格式、UTF8編碼，訪問域名為https://qyapi.weixin.qq.com，數據包不需要加密。

在每次主動調用企業號接口時需要帶上AccessToken參數。AccessToken參數由CorpID和Secret換取。

CorpID是企業號的標識，每個企業號擁有一個唯一的CorpID；Secret是管理組憑證密鑰。

系統管理員可通過管理端的權限管理功能創建管理組，分配管理組對應用、通訊錄、接口的訪問權限。完成后，管理組即可獲得唯一的secret。系統管理員可通過權限管理查看所有管理組的secret，其他管理員可通過設置中的開發者憑據查看。

當企業應用調用企業號接口時，企業號后台為根據此次訪問的AccessToken,校驗訪問的合法性以及所對應的管理組的管理權限以返回相應的結果。

注：你應該審慎配置管理組的權限，夠用即好，權限過大會增加誤操作可能性及信息安全隱患。

2、獲取AccessToken

AccessToken是企業號的全局唯一票據，調用接口時需攜帶AccessToken。

AccessToken需要用CorpID和Secret來換取，不同的Secret會返回不同的AccessToken。正 常情況下AccessToken有效期為7200秒，有效期內重復獲取返回相同結果，並自動續期。由於獲取access_token的api調用次數非常 有限，建議企業全局存儲與更新access_token，頻繁刷新access_token會導致api調用受限，影響自身業務。

• 請求說明

Https請求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=id&corpsecret=secrect

• 參數說明

參數	必須	說明
corpid	是	企業Id
corpsecret	是	管理組的憑證密鑰

• 權限說明

每個secret代表了對應用、通訊錄、接口的不同權限；不同的管理組擁有不同的secret。

• 返回說明

a)正確的Json返回結果:

{
   "access_token": "accesstoken000001",
}

參數	說明
access_token	獲取到的憑證

b)錯誤的Json返回示例:

{
   "errcode": 43003,
   "errmsg": "require https"
}

3、主動調用的頻率限制

當你獲取到AccessToken時，你的應用就可以成功調用企業號后台所提供的各種接口以管理或訪問企業號后台的資源或給企業號成員發消息。

為了防止企業應用的程序錯誤而引發企業號服務器負載異常，默認情況下，每個企業號調用接口都有一定的頻率限制，當超過此限制時，調用對應接口會收到相應錯誤碼。

以下是當前默認的頻率限制，企業號后台可能會根據運營情況調整此閾值：

• 基礎頻率

每企業調用單個cgi/api不可超過1000次/分，30000次/小時

每ip調用單個cgi/api不可超過2000次/分，60000次/小時

每ip獲取AccessToken不可超過300次/小時

• 發消息頻率

每企業不可超過200次/分鍾；不可超過帳號上限數*30人次/天

• 創建帳號頻率

每企業創建帳號數不可超過帳號上限數*3/月

 

二、回調模式

官方解釋

1、開啟應用的回調模式

　　在回調模式下，企業不僅可以主動調用企業號接口，還可以接收用戶的消息或事件。接收的信息使用XML數據格式、UTF8編碼，並以AES方式加密.

　　企業號的每個應用都有自己的回調模式開關。在管理端開啟並設置好相關參數后，此應用的回調模式才生效。

　　針對加解密的處理，微信提供了各種語言的庫，企業可以在附錄中下載。

　　當你開啟應用的回調模式時，企業號會要求你填寫應用的URL、Token、EncodingAESKey三個參數。

　　URL是企業應用接收企業號推送請求的訪問協議和地址，支持http或https協議。

　　Token可由企業任意填寫，用於生成簽名。

　　EncodingAESKey用於消息體的加密，是AES密鑰的Base64編碼。

　　驗證URL、Token以及加密的詳細處理請參考后續'接收消息時的加解密處理'的部分。

驗證URL有效性

當你提交以上信息時，企業號將發送GET請求到填寫的URL上，GET請求攜帶四個參數，企業在獲取時需要做urldecode處理，否則會驗證不成功

參數	描述	是否必帶
msg_signature	微信加密簽名，msg_signature結合了企業填寫的token、請求中的timestamp、nonce參數、加密的消息體	是
timestamp	時間戳	是
nonce	隨機數	是
echostr	加密的隨機字符串，以msg_encrypt格式提供。需要解密並返回echostr明文，解密后有random、msg_len、msg、$CorpID四個字段，其中msg即為echostr明文	首次校驗時必帶

企業通過參數msg_signature對請求進行校驗，如果確認此次GET請求來自企業號，那么企業應用對echostr參數解密並原樣返回echostr明文(不能加引號)，則接入驗證生效，回調模式才能開啟。

后續回調企業時都會在請求URL中帶上以上參數（echostr除外），校驗方式與首次驗證URL一致。

2、使用回調模式

企業號在回調企業URL時，會對消息體本身做AES加密，以XML格式POST到企業應用的URL上；企業在被動回復時，也需要對數據加密，以XML格式返回給微信。企業的回復支持文本、圖片、語音、視頻、圖文等格式。

微信服務器在五秒內收不到響應會斷掉連接，並且重新發起請求，總共重試三次。如果在調試中，發現員工無法收到響應的消息，可以檢查是否消息處理超時。

關於重試的消息排重，有msgid的消息推薦使用msgid排重。事件類型消息推薦使用FromUserName + CreateTime排重。

假如企業無法保證在五秒內處理並回復，可以直接回復空串，企業號不會對此作任何處理，並且不會發起重試。這種情況下，可以使用發消息接口進行異步回復。

假設企業回調URL為http://api.3dept.com。

• 請求說明：

http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&timestamp=13500001234&nonce=123412323

• 回調數據格式：

<xml>
   <ToUserName><![CDATA[toUser]]</ToUserName>
   <AgentID><![CDATA[toAgentID]]</AgentID>
   <Encrypt><![CDATA[msg_encrypt]]</Encrypt>
</xml>

1.msg_encrypt為經過加密的密文
2.AgentID為接收的應用id，可在應用的設置頁面獲取
3.ToUserName為企業號的CorpID

企業需要對msg_signature進行校驗，並解密msg_encrypt，得出msg的原文。

• 回復給微信的數據格式：

<xml>
   <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
   <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
   <TimeStamp>timestamp</TimeStamp>
   <Nonce><![CDATA[nonce]]></Nonce>
</xml>

3、接收消息時的加解密處理

企業可以直接使用微信提供的庫進行加解密的處理，目前提供的有c++/python/php/java/c#等語言版本。代碼提供了解密、加密、驗 證URL三個接口，企業可根據自身需要下載(參見附錄)。以下為庫函數的使用說明(以c++為例)，更詳細的加解密方案請參考附錄。

1）解密函數

int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);

• 參數說明

參數	必須	說明
sMsgSignature	是	從回調URL中獲取的msg_signature參數
sTimeStamp	是	從回調URL中獲取的timestamp參數
sNonce	是	從回調URL中獲取的nonce參數
sPostData	是	從回調URL中獲取的整個post數據
sMsg	是	用於返回解密后的msg，以xml組織

• 返回說明

請參閱附錄加密部分。

2）加密函數

int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);

• 參數說明

參數	必須	說明
sReplyMsg	是	返回的消息體原文
sTimeStamp	是	時間戳，調用方生成
sNonce	是	隨機數，調用方生成
sEncryptMsg	是	用於返回的密文，以xml組織

• 返回說明

請參閱附錄加密部分。

3）驗證URL函數

int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);

• 參數說明

參數	必須	說明
sMsgSignature	是	從回調URL中獲取的msg_signature參數
sTimeStamp	是	從回調URL中獲取的timestamp參數
sNonce	是	從回調URL中獲取的nonce參數
sEchoStr	是	從回調URL中獲取的echostr參數。注意，此參數必須是urldecode后的值
sReplyEchoStr	是	解密后的echostr，用於回包。注意，必須原樣返回，不要做加引號或其它處理

• 返回說明

請參閱附錄加密部分。

詳細步驟

在配置上有幾個注意的地方。

1、首要要有一個ICP備案的域名，一定要有ICP備案，后面需要；

2、EncodeAESKey不能隨機生成，之前官網提供是不能使用的，目前不知道，EncodeAESKey生成規則是32位明文經過base64加密后，去掉“=”，形成的43位密鑰；

3、替換JCE包，重啟服務

4、JDK版本要大於等於1.6

5、回調模式和主動調用模式在消息發送上也有很大不同：

          A：回調模式下，被動發送的消息需要時xml格式並進行加密，加密規則是首先進行AES加密，然后進行base64加密。

          B：主動發送消息，格式為json格式，不需要加密，但需要token

6、回調模式接受到真正的消息內容之后，注意回復，空消息即可，否則微信會認為消息接受失敗，會再次發送同一消息

7、在接受消息上，回調模式先通過配置的鏈接，以Get形式發送一個密文，我們需要在Get中解析密文，返回給微信，微信接受消息無誤之后，才會以Post形式將加密的真正內容發送過來，

8、主動調用模式是企業號給員工發消息，回調模式則是員工向企業號發送消息，

消息通過第三方服務器處理，最后經過微信服務器把消息發送給用戶

要開啟企業號的回調模式，首先要進行URL驗證，也就是說，你必須要有一個服務器，來保證在公網環境下能夠訪問你的這個URL，然后才能接着往下走。(如果沒有服務器的話，建議使用BAE比較好)。

2. 創建一個web項目，(注意必須是Dynamic Web Project項目),然后創建一個servlet類，來處理企業號發送的請求，命名任意，代碼如下：

Java code

package org.yhxz.weixin.servlet;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.qq.weixin.mp.aes.AesException;
import com.qq.weixin.mp.aes.WXBizMsgCrypt;

/**
* 核心請求處理類
*/
public class CoreServlet extends HttpServlet {
private static final long serialVersionUID = 4440739483644821986L;
String sToken = "5XaQ8cG6x2pULd";//這個Token是隨機生成，但是必須跟企業號上的相同
String sCorpID = "wx4edd47d3a6r4r991";//這里是你企業號的CorpID
String sEncodingAESKey = "jWmYm7qjusnxu65ZRjGtBxmz3KA1tkAj3ykkR6q2B2C";//這個EncodingAESKey是隨機生成，但是必須跟企業號上的相同
/**
* 確認請求來自微信服務器
* @throws IOException
*/
public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException{
// 微信加密簽名
String sVerifyMsgSig = request.getParameter("msg_signature");
// 時間戳
String sVerifyTimeStamp = request.getParameter("timestamp");
// 隨機數
String sVerifyNonce = request.getParameter("nonce");
// 隨機字符串
String sVerifyEchoStr = request.getParameter("echostr");
String sEchoStr; //需要返回的明文
PrintWriter out = response.getWriter();
WXBizMsgCrypt wxcpt;
try {
wxcpt = new WXBizMsgCrypt(sToken, sEncodingAESKey, sCorpID);
sEchoStr = wxcpt.VerifyURL(sVerifyMsgSig, sVerifyTimeStamp,sVerifyNonce, sVerifyEchoStr);
// 驗證URL成功，將sEchoStr返回
out.print(sEchoStr);
} catch (AesException e1) {
e1.printStackTrace();
}
}

/**
* 處理微信服務器發來的消息
*/
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
// TODO 消息的接收、處理、響應
}

}

聯系QQ877507054索要完整版代碼

 3. 接下來就要導入官方的業務類了，然后將其導入到你的項目中。這個可以在官方文檔上下載到(注意，雖然官方下載的實例代碼中也有驗證的代碼，但是不建議使用哪個Sample.java，如果不信的可以試試看，反正我用這個是沒通)
    下載地址是：
http://qydev.weixin.qq.com/java.zip,
請開發者使用jdk1.6或以上的版本。針對org.apache.commons.codec.binary.Base64，需要導入jar包commons-codec-1.9（或comm ons-codec-1.8等其他版本），我們有提供，官方下載地址：
http://commons.apache.org/proper/commons-codec/download_codec.cgi。

4. 如果出現異常java.security.InvalidKeyException:illegal Key Size的解決方案：

在官方網站下載JCE無限制權限策略文件（JDK7的下載地址：

http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

下載后解壓，可以看到local_policy.jar和US_export_policy.jar以及readme.txt。如果安裝了JRE，將兩個jar文件放到%JRE_HOME% \lib\security目錄下覆蓋原來的文件，如果安裝了JDK，將兩個jar文件放到%JDK_HOME%\jre\lib\security目錄下覆蓋原來文件。

5. 下來就是對web.xml文件的配置，代碼如下：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

<?xml version= "1.0"  encoding= "UTF-8" ?> <web-app version= "2.5"  xmlns= "http://java.sun.com/xml/ns/javaee"      xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"      xsi:schemaLocation="http: //java.sun.com/xml/ns/javaee       http: //java.sun.com/xml/ns/javaee/web-app_2_5.xsd">      <servlet>          <servlet-name>coreServlet</servlet-name>          <servlet- class >              org.yhxz.course.servlet.CoreServlet          </servlet- class >      </servlet>        <!-- url-pattern中配置的/coreServlet用於指定該Servlet的訪問路徑 -->      <servlet-mapping>          <servlet-name>coreServlet</servlet-name>          <url-pattern>/coreServlet</url-pattern>      </servlet-mapping>        <welcome-file-list>          <welcome-file>index.html</welcome-file>      </welcome-file-list> </web-app>

6. 然后將你的項目發布到服務器上，在瀏覽器中輸入URL，如果在你的Tomcat的控制台上出現NullPointException異常，就說明沒有問題(出現的原因是：請求的數據為空，這個你懂得)。
7. 接下來就在企業號后台上的操作了，開啟回調模式，輸入你的URL，隨機生成token和EncodingAESKey，點擊提交就可以驗證通過，注意一定要代碼中的和企業號上的token和EncodingAESKey是要一致的。

 

 

三、Weixin JS接口

Weixin JS接口是微信為你的H5應用提供開放原生能力的接口，你的應用可以利用這些接口使用更多的微信原生能力和微信的操控能力， 以使得你的應用有更強大的智能，更好的用戶體驗。

除了以下章節所描述的各類接口。拍照、上傳圖片、掃碼、微信支付、地理位置上報等更多的接口已經或正在抓緊開放中，更多信息也請參考微信相關網站了解.

1、隱藏微信中網頁右上角按鈕

企業號在有需要時（如不需要用戶分享某個頁面），可在網頁中通過JavaScript代碼隱藏網頁右上角按鈕。

• 接口調用代碼（JavaScript）

function onBridgeReady(){
 WeixinJSBridge.call('hideOptionMenu');
}

if (typeof WeixinJSBridge == "undefined"){
    if( document.addEventListener ){
        document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
    }else if (document.attachEvent){
        document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
        document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
    }
}else{
    onBridgeReady();
}

• 返回說明

隱藏底部導航欄沒有返回值。（需要顯示請把hideOptionMenu換成showOptionMenu）

2、隱藏微信中網頁底部導航欄

企業號在有需要時（如認為用戶在該頁面不會用到瀏覽器前進后退功能），可在網頁中通過JavaScript代碼隱藏網頁底部導航欄。

• 接口調用代碼（JavaScript）

function onBridgeReady(){
   WeixinJSBridge.call('hideToolbar');
}

if (typeof WeixinJSBridge == "undefined"){
    if( document.addEventListener ){
        document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
    }else if (document.attachEvent){
        document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
        document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
    }
}else{
    onBridgeReady();
}

• 返回說明

隱藏底部導航欄沒有返回值。（需要顯示頂部導航欄，請把hideToolbar換成showToolbar）

3、網頁獲取用戶網絡狀態

為了方便開發者根據用戶的網絡狀態來提供不同質量的服務，企業號可以在企業號內部的網頁中使用JavaScript代碼調用來獲取網絡狀態。

• 接口調用代碼（JavaScript）

function onBridgeReady(){
 WeixinJSBridge.invoke('getNetworkType',{},
        function(e){
            WeixinJSBridge.log(e.err_msg);
        });
}

if (typeof WeixinJSBridge == "undefined"){
    if( document.addEventListener ){
        document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
    }else if (document.attachEvent){
        document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
        document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
    }
}else{
    onBridgeReady();
}

• 返回說明

獲取用戶網絡狀態的返回值如下：

network_type:wifi wifi網絡
network_type:edge 非wifi,包含3G/2G
network_type:fail 網絡斷開連接
network_type:wwan（2g或者3g）

4、關閉當前網頁窗口

在微信內置瀏覽器中被訪問的網頁，可使用該JavaScript代碼關閉當前網頁。

主要使用場景： 微信用戶在企業號會話中點擊外鏈到達企業號的網頁，在用戶完成操作后，企業號（網頁方）可調用此接口關閉當前網頁窗口，使用戶返回會話。

• 接口調用代碼（JavaScript）

WeixinJSBridge.invoke('closeWindow',{},function(res){

    //alert(res.err_msg);

});

• 返回說明

 

返回值	說明
err_msg	關閉成功返回“close_window:ok”，關閉失敗返回“close_window:error”。

 

 

【編輯推薦】

1. 揭秘微信企業號：企業客戶的移動應用入口