微信開放平臺：朋友圈API參考文檔
用戶授權
客戶端的授權流程
針對沒有后臺服務器的 App 類型，如移動平臺的 App 應用，微信使用 OAuth2.0 的 Implicit Grant 方式授權，流程如下：
- 用戶訪問第三方應用，使用到分享至微信朋友圈的功能，應用檢測到沒有用戶的授權信息，于是將用戶引導至授權頁面;
- 當用戶未登錄時，將要求先登錄，否則繼續下一步;
- 授權頁面為一個對話框，顯示應用信息以及請求的訪問權限，并提示用戶選擇允許或拒絕;
- 對話框將重定向回應用，若授權成功則帶上 Access Token，否則帶上相應的錯誤碼。
客戶端授權流程得到的 Access Token 有效期為 2 小時，過期后需重新走授權流程。
服務器端的授權流程
服務端的授權流程為 OAuth2.0 定義的 Authentication Code Grant 的授權方式，我們推薦朋友圈應用使用服務端的授權流程。在該授權流程中，App 除了可以得到用戶的 AccessToken 外還有 RefreshToken， RefreshToken 過期時間為一年。
服務端的授權流程如下:
- 當用戶未登錄時，將要求先登錄，否則繼續下一步;
- 授權頁面為一個對話框，顯示應用信息以及請求的訪問權限，并提示用戶選擇允許或拒絕;
- 當用戶允許后，微信將以重定向的方式回到App，并帶上一個授權碼，否則將提示失敗;
- 第三方應用通過后臺訪問微信 API，通過授權碼換取Access Token和Refresh Token。
通過服務端的授權流程得到的 AccessToken 有效期為 30 天，過期后使用 RefreshToken 即可換取新的 AccessToken。
授權連接
URL: https://open.weixin.qq.com/oauth
| 參數列表 | 參數含義 |
|---|---|
| appid | 從微信開放平臺申請的AppId |
| response_type | 返回類型，值為code或token之一 |
| redirect_uri | 授權成功后的重定向頁面，默認為App預留在微信的uri |
| scope | 可選參數，所申請授權的資源域，以空格分開，目前僅支持并默認選擇post_timeline |
| state | 可選參數，自定義重定向uri的參數 |
服務端流程請求連接樣例:
https://open.weixin.qq.com/oauth?appid=hello&response_type=code
用戶成功授權后返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
用戶拒絕授權的返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied
客戶端流程請求連接樣例:
https://open.weixin.qq.com/oauth?appid=hello&response_type=token
用戶成功授權后返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=ASDFBCDEFGHIJKLMN&expires_in=259200
用戶拒絕授權的返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied
API列表
| 名稱 | 功能 |
|---|---|
| GET /token | 獲取Access Token |
| POST /media | 上傳附件 |
| GET /media/:media_id | 下載附件內容 |
| POST /timeline | 發表到朋友圈 |
GET /token
URL: https://api.weixin.qq.com/token.format
用于通過授權code換取access token和refresh token，或用于通過refresh token換取新的access token。
| 參數列表 | 參數含義 |
|---|---|
| grant_type | 獲取的token類型，authentication_code 或 refresh_token |
| code | 當grant_type為authentication_code時填寫，此為用戶授權后得到的授權碼 |
| refresh_token | 當grant_type為refresh_token時填寫 |
| redirect_uri | 當grant_type為authentication_code時填寫，需和oauth步驟所填寫的redirect_uri相同 |
當應用走服務器端的授權流程時，通過該API使用授權碼換取access token和refresh token，此時grant_type需設置為authentication_code，請求URL如下：
GET "https://api.weixin.qq.com/token?appid=wx1234hello" "&grant_type=authorization_code&code=4433222&redirect_Uri=" "http%3A//www.example.com/weixin_redirect"
返回樣例：
{
"refresh_token" : "93Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_
wwasdfLNNLfmn023mNA0nX",
"access_token" : "3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_Lj
JqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF
6yoKpfZkY2mIGBeaMZKsXcfWoTP94g",
"expires_in" : 7200
}
當access token過期時，可通過refresh token獲取新的access token，請求樣例：
GET "https://api.weixin.qq.com/token?appid=wx1234abcd" "&grant_type=refresh_token&secret=egs1mwxkfpt459" "&refresh_token=93Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_wwasdfLNNLfmn023mNA0nX"
返回樣例：
{
"access_token" : "K3Zkx2gyQVaeIbinDDmZ1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_
LjJqUNdYDYlyxrGOw1ywdGGb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF
6yoKpfZkY2mIGBeaMZKs",
"expires_in" : 7200
}
POST /media
URL: https://api.weixin.qq.com/media.format
| 參數列表 | 參數含義 |
|---|---|
| type | 附件類型，目前僅支持image |
| media[] | 附件內容 |
該API用于上傳一個附件到微信服務器，成功后將得到一個媒體id（media_id）表示該附件，從而分享至用戶朋友圈。
上傳的圖片大小限制為2M，如果原圖寬度超過640px，微信服務器將對圖片進行等比例縮放后存儲。
請求樣例（使用curl工具）：
curl -F "media=@test.jpg" "https://api.weixin.qq.com/media?type=image&access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
返回樣例：
{
"media_id" : "fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT",
"type" : "image",
"created_at" : 1335415865
}
GET /media/:media_id
URL: https://api.weixin.qq.com/media/:media_id.format
| 參數列表 | 參數含義 |
|---|---|
| media_id | 附件id |
該API用于下載媒體附件。
請求樣例（使用curl工具）：
curl "https://api.weixin.qq.com/media/fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
POST /timeline
URL: https://api.weixin.qq.com/timeline.format
| 參數列表 | 參數含義 |
|---|---|
| content_type | 指定消息的類型，必填，目前支持五類：text、photo、feed、video和music。 |
| title | 一句話描述，當content_type是feed時為必填字段。 對于content_type為feed，該字段可以是文章標題； 對于content_type為music，該字段可以是歌曲名和歌手； 對于content_type為video，該字段可以是視頻的名稱。 |
| media_list | media_id列表，content_type為feed、music和video時必填。多個media_id以“,”分隔。 當content_type為photo，最多可以提供9個media_id，多出部分會被拋棄。 當content_type為feed、music和video時，只可提供1個media_id作為消息的縮略圖，多出部分會被拋棄。 |
| media_url | 音樂文件地址，當content_type為music時必填。協議支持http和https，格式支持mp3和wav。 |
| content_url | 內容鏈接，當content_type為feed、music和video時必填 |
| coordinates | 經緯度，用“,”分隔，可選。數據格式為(latitude,longitude) |
該API用于分享內容至用戶的朋友圈中，title或media_list兩個參數至少選擇其中之一。
請求示例 1（使用curl工具）：
curl -d "title=hello&coordinates=10.00,10.00&media_list=fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT,fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT" "https://api.weixin.qq.com/timeline?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
成功返回：
{
"id" : 11232109051049549826,
"created_at" : 1333007682
}
失敗返回：
{
"time" : 1338972300,
"error" : { "msg": "content_url is missing", "code": 40329 }
}
請求示例 2：
curl -d "title=Complcated&coordinates=24.00,114.00&media_list=L5JPCzX96wnwcE4Hthh&content_url=http%3A%2F%2Fy.qq.com%2Fi%2Fsong.html%23p%3D7B2273&media_url=http%3A%2F%2Fy.qq.com%2Fi%2Fsong.html%23p%3D7B2273&content_type=music" "https://api.weixin.qq.com/timeline?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
請求示例2在微信朋友圈展示的效果圖如下：：
