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

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

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

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

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

一、主動(dòng)調(diào)用

1、簡(jiǎn)述

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

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

CorpID是企業(yè)號(hào)的標(biāo)識(shí)，每個(gè)企業(yè)號(hào)擁有一個(gè)唯一的CorpID；Secret是管理組憑證密鑰。

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

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

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

2、獲取AccessToken

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

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

• 請(qǐng)求說明

Https請(qǐng)求方式: GET

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

• 參數(shù)說明

參數(shù)	必須	說明
corpid	是	企業(yè)Id
corpsecret	是	管理組的憑證密鑰

• 權(quán)限說明

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

• 返回說明

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

{ 
   "access_token": "accesstoken000001", 
} 

參數(shù)	說明
access_token	獲取到的憑證

b)錯(cuò)誤的Json返回示例:

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

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

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

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

以下是當(dāng)前默認(rèn)的頻率限制，企業(yè)號(hào)后臺(tái)可能會(huì)根據(jù)運(yùn)營(yíng)情況調(diào)整此閾值：

• 基礎(chǔ)頻率

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

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

每ip獲取AccessToken不可超過300次/小時(shí)

• 發(fā)消息頻率

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

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

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

二、回調(diào)模式

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

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

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

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

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

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

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

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

驗(yàn)證URL、Token以及加密的詳細(xì)處理請(qǐng)參考后續(xù)'接收消息時(shí)的加解密處理'的部分。

驗(yàn)證URL有效性

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

參數(shù)	描述	是否必帶
msg_signature	微信加密簽名，msg_signature結(jié)合了企業(yè)填寫的token、請(qǐng)求中的timestamp、nonce參數(shù)、加密的消息體	是
timestamp	時(shí)間戳	是
nonce	隨機(jī)數(shù)	是
echostr	加密的隨機(jī)字符串，以msg_encrypt格式提供。需要解密并返回echostr明文，解密后有random、msg_len、msg、$CorpID四個(gè)字段，其中msg即為echostr明文	首次校驗(yàn)時(shí)必帶

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

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

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

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

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

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

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

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

• 請(qǐng)求說明：

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為接收的應(yīng)用id，可在應(yīng)用的設(shè)置頁面獲取

3.ToUserName為企業(yè)號(hào)的CorpID

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

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

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

3、接收消息時(shí)的加解密處理

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

1）解密函數(shù)

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

• 參數(shù)說明

參數(shù)	必須	說明
sMsgSignature	是	從回調(diào)URL中獲取的msg_signature參數(shù)
sTimeStamp	是	從回調(diào)URL中獲取的timestamp參數(shù)
sNonce	是	從回調(diào)URL中獲取的nonce參數(shù)
sPostData	是	從回調(diào)URL中獲取的整個(gè)post數(shù)據(jù)
sMsg	是	用于返回解密后的msg，以xml組織

• 返回說明

請(qǐng)參閱附錄加密部分。

2）加密函數(shù)

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

• 參數(shù)說明

參數(shù)	必須	說明
sReplyMsg	是	返回的消息體原文
sTimeStamp	是	時(shí)間戳，調(diào)用方生成
sNonce	是	隨機(jī)數(shù)，調(diào)用方生成
sEncryptMsg	是	用于返回的密文，以xml組織

• 返回說明

請(qǐng)參閱附錄加密部分。

3）驗(yàn)證URL函數(shù)

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

• 參數(shù)說明

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

• 返回說明

請(qǐng)參閱附錄加密部分。

三、Weixin JS接口

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

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

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

企業(yè)號(hào)在有需要時(shí)（如不需要用戶分享某個(gè)頁面），可在網(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(); 
} 

• 返回說明

隱藏底部導(dǎo)航欄沒有返回值。（需要顯示請(qǐng)把hideOptionMenu換成showOptionMenu）

2、隱藏微信中網(wǎng)頁底部導(dǎo)航欄

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

• 接口調(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(); 
} 

• 返回說明

隱藏底部導(dǎo)航欄沒有返回值。（需要顯示頂部導(dǎo)航欄，請(qǐng)把hideToolbar換成showToolbar）

3、網(wǎng)頁獲取用戶網(wǎng)絡(luò)狀態(tài)

為了方便開發(fā)者根據(jù)用戶的網(wǎng)絡(luò)狀態(tài)來提供不同質(zhì)量的服務(wù)，企業(yè)號(hào)可以在企業(yè)號(hào)內(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)閉當(dāng)前網(wǎng)頁窗口

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

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

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

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

• 返回說明

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