微信企業號開發之如何建立連接
連接將使你的企業號更具價值，你可以使用以下三種方式，連接你的企業號及企業應用：
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/月
#p#
二、回調模式
在回調模式下，企業不僅可以主動調用企業號接口，還可以接收用戶的消息或事件。接收的信息使用XML數據格式、UTF8編碼，并以AES方式加密。
企業號的每個應用都有自己的回調模式開關。在管理端開啟并設置好相關參數后，此應用的回調模式才生效。
針對加解密的處理，微信提供了各種語言的庫，企業可以在附錄中下載。
1、開啟應用的回調模式
當你開啟應用的回調模式時，企業號會要求你填寫應用的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×tamp=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，用于回包。注意，必須原樣返回，不要做加引號或其它處理 |
- 返回說明
請參閱附錄加密部分。
#p#
三、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”。 |
