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

1、企業(yè)應用調(diào)用企業(yè)號提供的接口，管理或查詢企業(yè)號后臺所管理的資源、或給成員發(fā)送消息等，以下稱主動調(diào)用模式。

2、企業(yè)號把用戶發(fā)送的消息或用戶觸發(fā)的事件推送給企業(yè)應用，由企業(yè)應用處理，以下稱回調(diào)模式。

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

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

一、主動調(diào)用

1、簡述

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

在每次主動調(diào)用企業(yè)號接口時需要帶上AccessToken參數(shù)。AccessToken參數(shù)由CorpID和Secret換取。

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

系統(tǒng)管理員可通過管理端的權(quán)限管理功能創(chuàng)建管理組，分配管理組對應用、通訊錄、接口的訪問權(quán)限。完成后，管理組即可獲得唯一的secret。系統(tǒng)管理員可通過權(quán)限管理查看所有管理組的secret，其他管理員可通過設(shè)置中的開發(fā)者憑據(jù)查看。

當企業(yè)應用調(diào)用企業(yè)號接口時，企業(yè)號后臺為根據(jù)此次訪問的AccessToken,校驗訪問的合法性以及所對應的管理組的管理權(quán)限以返回相應的結(jié)果。

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

2、獲取AccessToken

AccessToken是企業(yè)號的全局唯一票據(jù)，調(diào)用接口時需攜帶AccessToken。

AccessToken需要用CorpID和Secret來換取，不同的Secret會返回不同的AccessToken。正 常情況下AccessToken有效期為7200秒，有效期內(nèi)重復獲取返回相同結(jié)果，并自動續(xù)期。由于獲取access_token的api調(diào)用次數(shù)非常 有限，建議企業(yè)全局存儲與更新access_token，頻繁刷新access_token會導致api調(diào)用受限，影響自身業(yè)務。

• 請求說明

Https請求方式: GET

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

• 參數(shù)說明

• 權(quán)限說明

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

• 返回說明

a)正確的Json返回結(jié)果:

{ 
   "access_token": "accesstoken000001", 
} 

b)錯誤的Json返回示例:

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

3、主動調(diào)用的頻率限制

當你獲取到AccessToken時，你的應用就可以成功調(diào)用企業(yè)號后臺所提供的各種接口以管理或訪問企業(yè)號后臺的資源或給企業(yè)號成員發(fā)消息。

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

以下是當前默認的頻率限制，企業(yè)號后臺可能會根據(jù)運營情況調(diào)整此閾值：

• 基礎(chǔ)頻率

每企業(yè)調(diào)用單個cgi/api不可超過1000次/分，30000次/小時

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

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

• 發(fā)消息頻率

每企業(yè)不可超過200次/分鐘；不可超過帳號上限數(shù)*30人次/天

• 創(chuàng)建帳號頻率

每企業(yè)創(chuàng)建帳號數(shù)不可超過帳號上限數(shù)*3/月

#p#

二、回調(diào)模式

在回調(diào)模式下，企業(yè)不僅可以主動調(diào)用企業(yè)號接口，還可以接收用戶的消息或事件。接收的信息使用XML數(shù)據(jù)格式、UTF8編碼，并以AES方式加密。

企業(yè)號的每個應用都有自己的回調(diào)模式開關(guān)。在管理端開啟并設(shè)置好相關(guān)參數(shù)后，此應用的回調(diào)模式才生效。

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

1、開啟應用的回調(diào)模式

當你開啟應用的回調(diào)模式時，企業(yè)號會要求你填寫應用的URL、Token、EncodingAESKey三個參數(shù)。

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

Token可由企業(yè)任意填寫，用于生成簽名。

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

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

驗證URL有效性

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

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

后續(xù)回調(diào)企業(yè)時都會在請求URL中帶上以上參數(shù)（echostr除外），校驗方式與***驗證URL一致。

2、使用回調(diào)模式

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

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

關(guān)于重試的消息排重，有msgid的消息推薦使用msgid排重。事件類型消息推薦使用FromUserName + CreateTime排重。

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

假設(shè)企業(yè)回調(diào)URL為http://api.3dept.com。

• 請求說明：

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

• 回調(diào)數(shù)據(jù)格式：

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

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

企業(yè)需要對msg_signature進行校驗，并解密msg_encrypt，得出msg的原文。

• 回復給微信的數(shù)據(jù)格式：

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

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

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

1）解密函數(shù)

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

• 參數(shù)說明

• 返回說明

請參閱附錄加密部分。

2）加密函數(shù)

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

• 參數(shù)說明

• 返回說明

請參閱附錄加密部分。

3）驗證URL函數(shù)

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

• 參數(shù)說明

• 返回說明

請參閱附錄加密部分。

#p#

三、Weixin JS接口

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

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

1、隱藏微信中網(wǎng)頁右上角按鈕

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

• 接口調(diào)用代碼（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、隱藏微信中網(wǎng)頁底部導航欄

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

• 接口調(diào)用代碼（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、網(wǎng)頁獲取用戶網(wǎng)絡(luò)狀態(tài)

為了方便開發(fā)者根據(jù)用戶的網(wǎng)絡(luò)狀態(tài)來提供不同質(zhì)量的服務，企業(yè)號可以在企業(yè)號內(nèi)部的網(wǎng)頁中使用JavaScript代碼調(diào)用來獲取網(wǎng)絡(luò)狀態(tài)。

• 接口調(diào)用代碼（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(); 
} 

• 返回說明

獲取用戶網(wǎng)絡(luò)狀態(tài)的返回值如下：

network_type:wifi wifi網(wǎng)絡(luò) 
network_type:edge 非wifi,包含3G/2G 
network_type:fail 網(wǎng)絡(luò)斷開連接 
network_type:wwan（2g或者3g） 

4、關(guān)閉當前網(wǎng)頁窗口

在微信內(nèi)置瀏覽器中被訪問的網(wǎng)頁，可使用該JavaScript代碼關(guān)閉當前網(wǎng)頁。

主要使用場景： 微信用戶在企業(yè)號會話中點擊外鏈到達企業(yè)號的網(wǎng)頁，在用戶完成操作后，企業(yè)號（網(wǎng)頁方）可調(diào)用此接口關(guān)閉當前網(wǎng)頁窗口，使用戶返回會話。

• 接口調(diào)用代碼（JavaScript）

WeixinJSBridge.invoke('closeWindow',{},function(res){ 
 
    //alert(res.err_msg); 
 
}); 

• 返回說明