tencent cloud

开放接口
最后更新时间:2025-10-15 17:01:20
开放接口
最后更新时间: 2025-10-15 17:01:20

登录

login

该 API 使用方法为 wx.login(Object object)
功能说明:调用接口获取登录凭证,通过凭证进而换取用户登录态信息。
说明:
v2 版本(仅公有云支持),可参考实践教程说明。在 IDE(最低支持版本:2.1.111)中可直接调用。
v1 版本需要和superapp联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容。在 IDE 中可以使用 mock 面板进行返回值的 mock。
版本控制规则请参考 apiVersion 配置。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
code
string
用户登录凭证(有效期五分钟)。开发者需要在服务器后台调用 jscode2session,使用 code 换取 openid、session_key 等信息
object.fail 回调函数参数:Object err
属性
类型
说明
errMsg
string
错误信息
errno
Number
errno 错误码,错误码的详细说明参考 服务端错误码
示例代码:
wx.login({
success (res) {
if (res.code) {
//发起网络请求
wx.request({
url: 'https://example.com/onLogin',
data: {
code: res.code
}
})
} else {
console.log('登录失败!' + res.errMsg)
}
}
})

getAuthCode

该 API 使用方法为 wx.getAuthCode(Object object)
功能说明:实验性功能, 通过预自定义的 scope 获取一个授权码,需要小程序和 superapp 协商实现
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码
wx.getAuthCode({
scopes:["CUSTOM_SCOPE_X","CUSTOM_SCOPE_Y"],
success (res) {
if (res.code) {
//发起网络请求
wx.request({
url: 'https://example.com/onLogin',
data: {
code: res.code
}
})
} else {
console.log('登录失败!' + res.errMsg)
}
}
})

checkSession

该 API 使用方法为 wx.checkSession(Object object)
功能说明:检查登录态是否过期。
说明:
v2 版本(仅公有云支持),可参考实践文档说明。在 IDE(最低支持版本:2.1.111)中可直接调用。
session_key 具有唯一性,在使用小程序时,同一用户在同一时刻仅有一个有效的 session_key。
通过 wx.login 接口获得的用户登录态拥有一定的时效性,开发者可以调用 wx.checkSession 接口检测当前用户登录态是否有效。
wx.checkSession 的校验对象是最后一次获取 code 操作对应的登录态 session_key,调用成功说明该 session_key 未过期,调用失败说明 session_key 已过期。
登录态失效后开发者可以再调用 wx.login 获取新的用户登录态。
v1 版本需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容。在 IDE 中可以使用 mock 面板进行返回值的 mock。
版本控制规则请参考 apiVersion 配置。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.checkSession({
success () {
//session_key 未过期,并且在本生命周期一直有效
},
fail () {
// session_key 已经失效,需要重新执行登录流程
wx.login() //重新登录
}
})

用户信息

说明:
账号信息相关 API 小程序支持,小游戏暂不支持。

getUserProfile

该 API 使用方法为 wx.getUserProfile(Object object)
功能说明:IDE 目前暂不支持,该 API 需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容。
在 IDE 中可以使用 mock 面板进行返回值的 mock
获取用户信息
返回值:Object object。
属性
类型
默认值
必填
说明
lang
string
en
显示用户信息的语言,合法值为:
en:英文
zh_CN:简体中文
zh_TW:繁体中文
desc
string
-
声明获取用户个人信息后的用途,不超过30个字符
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)

getUserInfo

该 API 使用方法为 wx.getUserInfo(Object object)
功能说明:IDE 目前暂不支持,该 API 需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容
在 IDE 中可以使用 mock 面板进行返回值的 mock。
获取用户信息,该 API 需要区分首次调用和授权后调用,首次调用需要使用 <button open-type="getUserInfo" /> 组件进行用户授权,授权成功后,后续可以直接使用 wx.getUserInfo 方式进行调用
参数及说明:Object object。
属性
类型
默认值
必填
说明
lang
string
en
显示用户信息的语言,合法值为:
en:英文
zh_CN:简体中文
zh_TW:繁体中文
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
userInfo
UserInfo
用户信息对象
示例
小程序用户信息组件示例代码(用户授权)
<!-- 如果只是展示用户头像昵称,可以使用 <open-data /> 组件 -->
<open-data type="userAvatarUrl"></open-data>
<open-data type="userNickName"></open-data>
<!-- 需要使用 button 来授权登录 -->
<button wx:if="{{canIUse}}" open-type="getUserInfo" bindgetuserinfo="bindGetUserInfo">授权登录</button>
<view wx:else>请升级superapp版本</view>

Page({
data: {
canIUse: wx.canIUse('button.open-type.getUserInfo')
},
onLoad: function() {
// 查看是否授权userAvatarUrl
wx.getSetting({
success (res){
if (res.authSetting['scope.userInfo']) {
// 已经授权,可以直接调用 getUserInfo 获取头像昵称
wx.getUserInfo({
success: function(res) {
console.log(res.userInfo)
}
})
}
}
})
},
bindGetUserInfo (e) {
console.log(e.detail.userInfo)
}
})
示例代码:
// 必须是在用户已经授权的情况下调用
wx.getUserInfo({
success: function(res) {
var userInfo = res.userInfo
var nickName = userInfo.nickName
var avatarUrl = userInfo.avatarUrl
}
})

userInfo

功能说明:用户信息,通常我们建议在自定义返回内容的时候,需要将以下属性返给小程序,方便小程序后续业务逻辑处理。
参数及说明:
属性
类型
说明
nickName
string
用户昵称
avatarUrl
string
用户头像图片的 URL。URL 最后一个数值代表正方形头像大小(有 0、46、64、96、132 数值可选,0 代表 640x640 的正方形头像,46 表示 46x46 的正方形头像,剩余数值以此类推。默认132),用户没有头像时该项为空。若用户更换头像,原有头像 URL 将失效
gender
number
用户性别。不再返回,合法值为:
0:未知
1:男性
2:女性
country
string
用户所在国家。不再返回
province
string
用户所在省份。不再返回
city
string
用户所在城市。不再返回
language
string
显示 country,province,city 所用的语言。强制返回 “zh_CN”,合法值为:
en:英文
zh_CN:简体中文
zh_TW:繁体中文

chooseAvatar

该 API 使用方法为 <button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar"> ... </button>
功能说明:IDE 目前支持 Mock 数据的返回,获取 superapp 用户头像,在真机上返回的内容是由 superapp 提供
返回值:用户头像 URL 示例
示例代码
wxml
javascript
<button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">
<image src="{{userHead}}" class="userHead" mode="aspectFill" />
</button>
Page({
data: {
userHead: defaultAvatar,
},
onChooseAvatar(e) {
console.log('onChooseAvatar===', e)
const { avatarUrl } = e.detail;
if (avatarUrl) {
this.setData({
userHead: avatarUrl,
})
}
},
})

getNickName

该 API 使用方法为 <input type="nickname" class="value" placeholder="请输入昵称" />
功能说明:IDE 目前支持 Mock 数据的返回,获取 superapp 用户昵称,在真机上返回的内容是由 superapp 提供
返回值:用户昵称,示例
示例代码
wxml
<view class="settingItem">
<text class="caption">昵称</text>
<input type="nickname" class="value" placeholder="请输入昵称" />
</view>

敏感信息

getPhoneNumber

该 API 使用方法为 <button open-type="getPhoneNumber" bindgetphonenumber="handleGetPhoneNumber"> ... </button>
功能说明:IDE 目前支持 Mock 数据的返回,获取 superapp 用户手机号,在真机上返回的内容是由 superapp 提供
返回值:code 示例
其他说明: code换取手机号接口
示例代码
wxml
javascript
<button
class="button"
type="default"
size="mini"
open-type="getPhoneNumber"
bindgetphonenumber="handleGetPhoneNumber">
获取手机号码
</button>
Page({
handleGetPhoneNumber(e) {
const { code, errMsg } = e.detail
if (code) {
// 发起网络请求从后台获取手机号
wx.request({
url: 'https://example.com/getPhoneNumber',
data: {code},
success: res => console.log('phone:', res)
})
} else {
console.error(errMsg)
}
},
});

getEmailAddress

该 API 使用方法为 <button open-type="getEmailAddress" bindgetemailaddress="handleGetEmailAddress"> ... </button>
功能说明:IDE 目前支持 Mock 数据的返回,获取 superapp 用户邮箱,在真机上返回的内容是由 superapp 提供
返回值:code 示例
其他说明: code换取邮箱接口
示例代码
wxml
javascript
<button
class="button"
type="default"
size="mini"
open-type="getEmailAddress"
bindgetemailaddress="handleGetEmailAddress">
获取邮箱
</button>
Page({
handleGetEmailAddress(e) {
const { code, errMsg } = e.detail
if (code) {
// 发起网络请求从后台获取邮箱
wx.request({
url: 'https://example.com/getEmail',
data: {code},
success: res => console.log('mail:', res)
})
} else {
console.error(errMsg)
}
},
});


支付

requestPayment

该 API 使用方法为 wx.requestPayment(Object object)
功能说明:调起 superapp 的支付,该 API 首先需要 superapp 具备支付能力并完成支付流程的对接。通常情况下,我们建议开发者参考我们的小程序支付和商户实践教程进行 API 实现,最佳实践需要 superapp 开发者和小程序开发者共同参与,最佳实践能够有效的保证数据安全和支付扩展性。
须知:通常来说 timeStamp、nonceStr、package、signType、paySign 这几个参数应该由小程序后台生成。在小程序前端调用小程序后台下单接口的时候返回,然后通过上述返回值调用 wx.requestPayment 发起支付流程。
参数及说明:Object object。
属性
类型
默认值
必填
说明
timeStamp
string
-
时间戳,从 1970 年 1 月 1 日 00:00:00 至今的秒数,即当前的时间
nonceStr
string
-
随机字符串,长度为32个字符以下
package
string
-
统一下单接口返回的 prepay_id 参数值,提交格式如:prepay_id=***
signType
string
-
签名算法,应与后台下单时的值一致 通常是: RSA
paySign
string
-
签名,具体见支付和商户实践教程
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.requestPayment({
timeStamp: '',
nonceStr: '',
package: '',
signType: 'RSA',
paySign: '',
success (res) {
/* res通常由superapp返回给小程序前端,结构由superapp自定义
* 按照标准实现,支付成功后 会在这里收到 res.errMsg = ‘requestPayment:ok’
* 建议小程序在成功回调里,再调用小程序后台接口进行支付状态的确认。确保支付回调信息已经同步到小程序后台
*/
if(res.errMsg === 'resquestPayment:ok'){
// send request to miniprogram backend to comfirm payment state
}
},
fail (err) {
// 该错误内容通常由superapp返回给小程序前端,需要由小程序前端进行报错后的相关用户引导提示
}
})
如果客户的系统中已经有一套成熟的可靠的支付流程,可以结合自定义 API 和该 API 进行支付流程的自定义。


订阅消息

requestSubscribeMessage

该 API 使用方法为 wx.requestSubscribeMessage(Object object)
功能说明:调起 superapp 的小程序订阅消息界面,返回用户订阅消息的操作结果。通过 wx.getSetting 接口可获取用户对相关模板消息的订阅状态。
说明:
仅公有云支持。
一次性模板 id 和永久模板 id 不可同时使用。
一次授权调用里,每个 tmplId 对应的模板标题不能存在相同的,若出现相同的,只保留一个。
参数及说明:Object object。
属性
类型
默认值
必填
说明
tmplIds
Array
-
需要订阅的消息模板的id的集合,一次调用最多可订阅3条消息。消息模板id在控制台[小程序管理-订阅消息]中配置。每个 tmplId 对应的模板标题需要不相同,否则会被过滤。
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
errMsg
String
接口调用成功时 errMsg 值为 'requestSubscribeMessage:ok'
[TEMPLATE_ID: string]
String
[TEMPLATE_ID]是动态的键,即模板 id,值包括'accept'、'reject'、'ban'、'filter'
'accept':表示用户同意订阅该条 id 对应的模板消息
'reject':表示用户拒绝订阅该条 id 对应的模板消息
'ban':表示已被后台封禁
'filter':表示该模板因为模板标题同名被后台过滤
例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用户同意订阅zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE这条消息
object.fail 回调函数参数:Object err
属性
类型
说明
errMsg
String
接口调用失败错误信息
errno
Number
接口调用失败错误码
错误码
errCode
errMsg
说明
10001
TmplIds can't be empty
参数传空了
10002
Request list fail
网络问题,请求消息列表失败
10003
Request subscribe fail
网络问题,订阅请求发送失败
20001
No template data return, verify the template id exist
没有模板数据,一般是模板 ID 不存在或者和模板类型不对应导致的
20002
Templates type must be same
模板消息类型 既有一次性的又有永久的
20003
Templates count out of max bounds
模板消息数量超过上限
20004
The main switch is switched off
用户关闭了主开关,无法进行订阅
20005
This mini program was banned from subscribing messages
小程序被禁封
20013
Reject DeviceMsg Template
不允许通过该接口订阅设备消息
示例代码:
wx.requestSubscribeMessage({
tmplIds: [''],
success: (res) => {
console.log('requestSubscribeMessage===success', res)
}
})

本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈