欢迎光临
我们一直在努力
        找回密码
当前位置：达维营-前端网 > 小程序 > 正文

小程序文档整理之 — API（开放接口）

2017-07-21 分类：小程序 阅读(5231) 评论(0)

接口说明官方地址：https://mp.weixin.qq.com/debug/wxadoc/dev/api/

登录

wx.login(OBJECT)

调用接口获取登录凭证（code）进而换取用户登录态信息，包括用户的唯一标识（openid） 及本次登录的 会话密钥（session_key）等。用户数据的加解密通讯需要依赖会话密钥完成。

注：调用 login 会引起登录态的刷新，之前的 sessionKey 可能会失效。

 wx.login({
      success: function(res) {
          res.code//用户登录凭证（有效期五分钟）。开发者需要在开发者服务器后台调用 api，使用 code 换取 openid 和 session_key 等信息
          res.errMsg//调用结果
      },
      fail/complete: function(res) {//接口调用失败/结束的回调函数
      },
    });

code 换取 session_key(后台做的，不需要前台做)

​这是一个 HTTPS 接口，开发者服务器使用登录凭证 code 获取 session_key 和 openid。

session_key 是对用户数据进行加密签名的密钥。为了自身应用安全，session_key 不应该在网络上传输。

接口地址：

https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

请求参数：

https://api.weixin.qq.com/sns/jscode2session
?appid=APPID//(必要)小程序唯一标识
&secret=SECRET(必要)小程序的 app secret
&js_code=JSCODE//(必要)登录时获取的 code
&grant_type=authorization_code//(必要)填写为 authorization_code

 

返回参数
//正常返回的JSON数据包
{
      "openid": "OPENID",//用户唯一标识
      "session_key": "SESSIONKEY",//会话密钥
      "unionid": "UNIONID"//用户在开放平台的唯一标识符。本字段在满足一定条件的情况下才返回。具体参看UnionID机制说明
}
//错误时返回JSON数据包(示例为Code无效)
{
    "errcode": 40029,
    "errmsg": "invalid code"
}

 

wx.checkSession(OBJECT)

通过上述接口获得的用户登录态拥有一定的时效性。用户越久未使用小程序，用户登录态越有可能失效。反之如果用户一直在使用小程序，则用户登录态一直保持有效。具体时效逻辑由微信维护，对开发者透明。开发者只需要调用wx.checkSession接口检测当前用户登录态是否有效。登录态过期后开发者可以再调用wx.login获取新的用户登录态。

wx.checkSession({
  success: function(){//接口调用成功的回调函数，登录态未过期
    //session 未过期，并且在本生命周期一直有效
  },
  fail: function(){//接口调用失败的回调函数，登录态已过期
    //登录态过期
    wx.login() //重新登录
    ....
  },
  complete: function(){//接口调用结束的回调函数（调用成功、失败都会执行）
  }
})

 

登录态维护

通过 wx.login 获取到用户登录态之后，需要维护登录态。

开发者要注意不应该直接把 session_key、openid 等字段作为用户的标识或者 session 的标识，而应该自己派发一个 session 登录态（请参考登录时序图）。对于开发者自己生成的 session，应该保证其安全性且不应该设置较长的过期时间。session 派发到小程序客户端之后，可将其存储在 storage ，用于后续通信使用。

通过 wx.checkSession 可以检测用户登录态是否失效。并决定是否调用 wx.login 重新获取登录态

用户数据的签名验证和加解密

数据签名校验

为了确保 开放接口 返回用户数据的安全性，微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验，确保数据的完整性。

1、签名校验算法涉及用户的session_key，通过 wx.login 登录流程获取用户session_key，并自行维护与应用自身登录态的对应关系。
2、通过调用接口（如 wx.getUserInfo）获取数据时，接口会同时返回 rawData、signature，其中 signature = sha1( rawData + session_key )
3、开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ，比对 signature 与 signature2 即可校验数据的完整性。

如wx.getUserInfo的数据校验：

接口返回的rawData：

{
  "nickName": "Band",
  "gender": 1,
  "language": "zh_CN",
  "city": "Guangzhou",
  "province": "Guangdong",
  "country": "CN",
  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"
}

用户的 session-key：
HyVFkGl5F5OQWJZZaNzBBg==

所以，用于签名的字符串为：

{"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

使用sha1得到的结果为
75e81ceda165f4ffa64f4068af58c64b8f54b88c

 

加密数据解密算法

接口如果涉及敏感数据（如wx.getUserInfo当中的 openId 和unionId ），接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据，需要对接口返回的加密数据( encryptedData )进行对称解密。 解密算法如下：

1、对称解密使用的算法为 AES-128-CBC，数据采用PKCS#7填充。
2、对称解密的目标密文为 Base64_Decode(encryptedData)。
3、对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。
4、对称解密算法初始向量 为Base64_Decode(iv)，其中iv由数据接口返回。

微信官方提供了多种编程语言的示例代码（点击下载）。每种语言类型的接口名字均一致。调用方式可以参照示例。

另外，为了应用能校验数据的有效性，会在敏感数据加上数据水印( watermark )

如接口wx.getUserInfo敏感数据当中的watermark：

{
    "openId": "OPENID",
    "nickName": "NICKNAME",
    "gender": GENDER,
    "city": "CITY",
    "province": "PROVINCE",
    "country": "COUNTRY",
    "avatarUrl": "AVATARURL",
    "unionId": "UNIONID",
    "watermark"://数据水印
    {
        "appid":"APPID",//敏感数据归属appid，开发者可校验此参数与自身appid是否一致
        "timestamp":TIMESTAMP//敏感数据获取的时间戳, 开发者可以用于数据时效性校验
    }
}

 

注：
1、此前提供的加密数据（encryptData）以及对应的加密算法将被弃用，请开发者不要再依赖旧逻辑。
2、解密后得到的json数据根据需求可能会增加新的字段，旧字段不会改变和删减，开发者需要预留足够的空间

授权

部分接口需要获得用户授权同意后才能调用。此类接口调用时：

  • 如果用户未接受或拒绝过此权限，会弹窗询问用户，用户点击同意后方可调用接口；
  • 如果用户已授权，可以直接调用接口；
  • 如果用户已拒绝授权，则短期内不会出现弹窗，而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

获取授权信息 wx.getSetting(OBJECT)

获取用户的当前设置
注：返回值中只会出现小程序已经向用户请求过的权限

wx.getSetting({
  success: (res) => {
    /*
     * res.authSetting = {用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: (res) => {//接口调用失败/结束的回调函数
  }
})

 

打开设置界面 wx.openSetting(OBJECT)

用户可以在小程序设置界面（右上角 – 关于 – 右上角 – 设置）中控制对该小程序的授权状态。

开发者可以调用 wx.openSetting 打开设置界面，引导用户开启授权。

wx.openSetting({
  success: (res) => {
    /*
     * res.authSetting = {用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: (res) => {//接口调用失败/结束的回调函数
  }
})

 

提前发起授权请求 wx.authorize(OBJECT)

提前向用户发起授权请求。调用后会立刻弹窗询问用户是否同意授权小程序使用某项功能或获取用户的某些数据，但不会实际调用对应接口。如果用户之前已经同意授权，则不会出现弹窗，直接返回成功。

// 可以通过 wx.getSetting 先查询一下用户是否授权了 "scope.record" 这个 scope
wx.getSetting({
    success(res) {
        if (!res.authSetting['scope.record']) {
            wx.authorize({//提前向用户发起授权请求
                scope: 'scope.record',//(必填)需要获取权限的scope
                success() {
                    errMsg//调用结果
                    // 用户已经同意小程序使用录音功能，后续调用 wx.startRecord 接口不会弹窗询问
                    wx.startRecord()
                },
                fail/complete(){//接口调用失败/结束的回调函数
                }
            })
        }
    }
})

 

scope 列表

scope 对应接口 描述
scope.userInfo wx.getUserInfo 用户信息
scope.userLocation wx.getLocation, wx.chooseLocation 地理位置
scope.address wx.chooseAddress 通讯地址
scope.invoiceTitle wx.chooseInvoiceTitle 发票抬头
scope.werun wx.getWeRunData 微信运动步数
scope.record wx.startRecord 录音功能

| scope.writePhotosAlbum| wx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum | 保存到相册 |

用户信息

获取用户信息，withCredentials 为 true 时需要先调用 wx.login 接口。
需要用户授权 scope.userInfo

wx.getUserInfo({
  withCredentials//是否带上登录态信息
  lang//指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。默认为en。
  success: function(res) {//接口调用成功的回调函数
    var userInfo = res.userInfo//用户信息对象，不包含 openid 等敏感信息
    var userInfo = res.userInfo
    var nickName = userInfo.nickName
    var avatarUrl = userInfo.avatarUrl
    var gender = userInfo.gender //性别 0：未知、1：男、2：女
    var province = userInfo.province
    var city = userInfo.city
    var country = userInfo.country
    res.rawData//不包括敏感信息的原始数据字符串，用于计算签名
    res.signature//使用 sha1( rawData + sessionkey ) 得到字符串，用于校验用户信息
    res.encryptedData//包括敏感数据在内的完整用户信息的加密数据，详细见加密数据解密算法
    res.iv//加密算法的初始向量，详细见加密数据解密算法
  },
  fail/complete: function(){//接口调用失败/结束的回调函数
  }
})

encryptedData 解密后为以下 json 结构，详见加密数据解密算法
{
    "openId": "OPENID",
    "nickName": "NICKNAME",
    "gender": GENDER,
    "city": "CITY",
    "province": "PROVINCE",
    "country": "COUNTRY",
    "avatarUrl": "AVATARURL",
    "unionId": "UNIONID",
    "watermark":
    {
        "appid":"APPID",
    "timestamp":TIMESTAMP
    }
}

 

注：当 withCredentials 为 true 时，要求此前有调用过 wx.login 且登录态尚未过期，此时返回的数据会包含 encryptedData, iv 等敏感信息；当 withCredentials 为 false 时，不要求有登录态，返回的数据不包含 encryptedData, iv 等敏感信息。

getPhoneNumber(OBJECT)

获取微信用户绑定的手机号，需先调用login接口。

说明

因为需要用户主动触发才能发起获取手机号接口，所以该功能不由 API 来调用，需用 组件的点击来触发。

注意：目前该接口针对非个人开发者，且完成了认证的小程序开放。需谨慎使用，若用户举报较多或被发现在不必要场景下使用，微信有权永久回收该小程序的该接口权限。

使用方法

需要将 组件 open-type 的值设置为 getPhoneNumber，当用户点击并同意之后，可以通过 bindgetphonenumber 事件回调获取到微信服务器返回的加密数据， 然后在第三方服务端结合 session_key 以及 app_id 进行解密获取手机号。

注意

在回调中调用 wx.login 登录，可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey，导致解密失败。建议开发者提前进行 login；或者在回调中先使用 checkSession 进行登录态检查，避免 login 刷新登录态。

<button open-type="getPhoneNumber" bindgetphonenumber="getPhoneNumber"> </button>
Page({ 
    getPhoneNumber: function(e) { 
        console.log(e.detail.errMsg) 
        console.log(e.detail.iv) //加密算法的初始向量，详细见加密数据解密算法
        console.log(e.detail.encryptedData) //包括敏感数据在内的完整用户信息的加密数据，详细见加密数据解密算法
    } 
})

encryptedData 解密后为以下 json 结构，详见加密数据解密算法

{
    "phoneNumber": "13580006666",  //用户绑定的手机号（国外手机号会有区号）
    "purePhoneNumber": "13580006666", //没有区号的手机号
    "countryCode": "86",//区号
    "watermark":
    {
        "appid":"APPID",
        "timestamp":TIMESTAMP
    }
}

 

UnionID机制说明

如果开发者拥有多个移动应用、网站应用、和公众帐号（包括小程序），可通过unionid来区分用户的唯一性，因为只要是同一个微信开放平台帐号下的移动应用、网站应用和公众帐号（包括小程序），用户的unionid是唯一的。换句话说，同一用户，对同一个微信开放平台下的不同应用，unionid是相同的。

同一个微信开放平台下的相同主体的App、公众号、小程序，如果用户已经关注公众号，或者曾经登录过App或公众号，则用户打开小程序时，开发者可以直接通过wx.login获取到该用户UnionID，无须用户再次授权。

微信支付

wx.requestPayment(OBJECT)

发起微信支付

wx.requestPayment({
   'timeStamp': '',//时间戳从1970年1月1日00:00:00至今的秒数,即当前的时间
   'nonceStr': '',//随机字符串，长度为32个字符以下
   'package': '',//统一下单接口返回的 prepay_id 参数值，提交格式如：prepay_id=*
   'signType': 'MD5',//签名算法，暂支持 MD5
   'paySign': '',//签名,具体签名方案参见小程序支付接口文档;
   'success':function(res){
       res.errMsg//requestPayment:ok 调用支付成功
   },
   'fail':function(res){
       res.errMsg//requestPayment:fail cancel   用户取消支付
                 //requestPayment:fail (detail message) 调用支付失败，其中 detail message 为后台返回的详细失败原因
   },
   'complete': function(res){//接口调用结束的回调函数
   }
})

 

bug: 6.5.2 及之前版本中，用户取消支付不会触发 fail 回调，只会触发 complete 回调，回调 errMsg 为 ‘requestPayment:cancel’

模板消息

基于微信的通知渠道，我们为开发者提供了可以高效触达用户的模板消息能力，以便实现服务的闭环并提供更佳的体验。

模板推送位置：服务通知

模板下发条件：用户本人在微信体系内与页面有交互行为后触发，详见下发条件说明

模板跳转能力：点击查看详情仅能跳转下发模板的该帐号的各个页面

使用说明

步骤一：获取模板ID
有两个方法可以获取模版ID
通过模版消息管理接口获取模版ID（详见模版消息管理）
在微信公众平台手动配置获取模版ID
登录https://mp.weixin.qq.com 获取模板，如果没有合适的模板，可以申请添加新模板，审核通过后可使用，详见模板审核说明

步骤二：页面的 组件，属性report-submit为true时，可以声明为需发模板消息，此时点击按钮提交表单可以获取formId，用于发送模板消息。或者当用户完成支付行为，可以获取prepay_id用于发送模板消息。

步骤三：调用接口下发模板消息（详见发送模版消息）

模版消息管理

1.获取小程序模板库标题列表
接口地址

https://api.weixin.qq.com/cgi-bin/wxopen/template/library/list?access_token=ACCESS_TOKEN

//post
{
"access_token://(必要)接口调用凭证
"offset":0,//(必要)offset和count用于分页，表示从offset开始，拉取count条记录，offset从0开始，count最大为20
"count":5//(必要)offset和count用于分页，表示从offset开始，拉取count条记录，offset从0开始，count最大为20
}
返回码说明：
正常时的返回JSON数据包示例：

{
    "errcode":0,
    "errmsg":"ok",
    "list":[
        {
            "id":"AT0002",//模板标题id（获取模板标题下的关键词库时需要）
            "title":"购买成功通知"//模板标题内容
        }
    ],
    "total_count":599//模板库标题总数
}

 

2.获取模板库某个模板标题下关键词库
接口地址

https://api.weixin.qq.com/cgi-bin/wxopen/template/library/get?access_token=ACCESS_TOKEN

//post
{
"access_token"//接口调用凭证
"id":"AT0002"//(必要)模板标题id，可通过接口获取，也可登录小程序后台查看获取
}

返回码说明：
正常时的返回JSON数据包示例：
{
    "errcode": 0,
    "errmsg": "ok",
    "id": "AT0002",
    "title": "购买成功通知",
    "keyword_list": [
        {
            "keyword_id": 3,//关键词id，添加模板时需要
            "name": "购买地点",//关键词内容
            "example": "TIT造舰厂"//关键词内容对应的示例
        },
        {
            "keyword_id": 4,
            "name": "购买时间",
            "example": "2016年6月6日"
        },
        {
            "keyword_id": 5,
            "name": "物品名称",
            "example": "咖啡"
        }
    ]
}

 

3.组合模板并添加至帐号下的个人模板库
接口地址

https://api.weixin.qq.com/cgi-bin/wxopen/template/add?access_token=ACCESS_TOKEN

//post
{
"id":"AT0002", //(必要)模板标题id，可通过接口获取，也可登录小程序后台查看获取
"keyword_id_list":[3,4,5] //(必要)开发者自行组合好的模板关键词列表，关键词顺序可以自由搭配（例如[3,5,4]或[4,5,3]），最多支持10个关键词组合
}

返回码说明：
正常时的返回JSON数据包示例：
{
    "errcode": 0,
    "errmsg": "ok",
    "template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"//添加至帐号下的模板id，发送小程序模板消息时所需
}

 

4.获取帐号下已存在的模板列表
接口地址

https://api.weixin.qq.com/cgi-bin/wxopen/template/list?access_token=ACCESS_TOKEN

//post
{
"offset":0,//offset和count用于分页，表示从offset开始，拉取count条记录，offset从0开始，count最大为20。最后一页的list长度可能小于请求的count
"count":1//offset和count用于分页，表示从offset开始，拉取count条记录，offset从0开始，count最大为20。最后一页的list长度可能小于请求的count
}

返回码说明：
正常时的返回JSON数据包示例：
{
"errcode": 0,
"errmsg": "ok",
"list": [//帐号下的模板列表
        {
            "template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc",//添加至帐号下的模板id，发送小程序模板消息时所需
            "title": "购买成功通知",//模板标题
            "content": "购买地点{{keyword1.DATA}}\n购买时间{{keyword2.DATA}}\n物品名称{{keyword3.DATA}}\n",//模板内容
            "example": "购买地点：TIT造舰厂\n购买时间：2016年6月6日\n物品名称：咖啡\n"//模板内容示例
        }
    ]
}

 

5.删除帐号下的某个模板
接口地址

https://api.weixin.qq.com/cgi-bin/wxopen/template/del?access_token=ACCESS_TOKEN

//post
{
    "template_id"://(必要)"wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"//要删除的模板id
}

返回码说明：
正常时的返回JSON数据包示例：
{
    "errcode": 0,
    "errmsg": "ok"
}

 

发送模板消息

1、 获取 access_token

access_token 是全局唯一接口调用凭据，开发者调用各接口时都需使用 access_token，请妥善保存。access_token 的存储至少要保留512个字符空间。access_token 的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的 access_token 失效。

接口地址：

https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

//get 传参说明
grant_type=client_credential//(必要)获取 access_token 填写 client_credential
appid=APPID//(必要)第三方用户唯一凭证
secret=APPSECRET//(必要)第三方用户唯一凭证密钥，即appsecret

返回参数说明：

正常情况下，微信会返回下述 JSON 数据包给开发者：
{
    "access_token": "ACCESS_TOKEN", //获取到的凭证
    "expires_in": 7200//凭证有效时间，单位：秒
}

错误时微信会返回错误码等信息，JSON 数据包示例如下（该示例为 AppID 无效错误）:
{
    "errcode": 40013,
    "errmsg": "invalid appid"
}

 

2、发送模板消息

接口地址：(ACCESS_TOKEN 需换成上文获取到的 access_token)

https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN

//post 参数
{
  "touser": "OPENID",//(必要)接收者（用户）的 openid  
  "template_id": "TEMPLATE_ID", //(必要)所需下发的模板消息的id
  "page": "index",//点击模板卡片后的跳转页面，仅限本小程序内的页面。支持带参数,（示例index?foo=bar）。该字段不填则模板无跳转。   
  "form_id": "FORMID", //(必要)表单提交场景下，为 submit 事件带上的 formId；支付场景下，为本次支付的 prepay_id        
  "data": {//(必要)模板内容，不填则下发空模板
      "keyword1": {
          "value": "339208499", 
          "color": "#173177"
      }, 
      "keyword2": {
          "value": "2015年01月05日 12:30", 
          "color": "#173177"
      }, 
      "keyword3": {
          "value": "粤海喜来登酒店", 
          "color": "#173177"
      } , 
      "keyword4": {
          "value": "广州市天河区天河路208号", 
          "color": "#173177"
      } 
  },
  "color":"red"//模板内容字体的颜色，不填默认黑色
  "emphasis_keyword": "keyword1.DATA" //模板需要放大的关键词，不填则默认无放大
}

返回码说明：
正常时的返回JSON数据包示例：
{
  "errcode": 0,
  "errmsg": "ok"
}

错误时会返回错误码信息，说明如下：
返回码 说明
40037   template_id不正确
41028   form_id不正确，或者过期
41029   form_id已被使用
41030   page不正确
45009   接口调用超过限额（目前默认每个帐号日调用限额为100万）

 

3、下发条件说明

1)支付
当用户在小程序内完成过支付行为，可允许开发者向用户在7天内推送有限条数的模板消息（1次支付可下发3条，多次支付下发条数独立，互相不影响）

2)提交表单
当用户在小程序内发生过提交表单行为且该表单声明为要发模板消息的，开发者需要向用户提供服务时，可允许开发者向用户在7天内推送有限条数的模板消息（1次提交表单可下发1条，多次提交下发条数独立，相互不影响）

4、审核说明

1.标题
1.1标题不能存在相同
1.2标题意思不能存在过度相似
1.3标题必须以“提醒”或“通知”结尾
1.4标题不能带特殊符号、个性化字词等没有行业通用性的内容
1.5标题必须能体现具体服务场景
1.6标题不能涉及营销相关内容，包括不限于：消费优惠类、购物返利类、商品更新类、优惠券类、代金券类、红包类、会员卡类、积分类、活动类等营销倾向通知

2.关键词
2.1同一标题下，关键词不能存在相同
2.2同一标题下，关键词不能存在过度相似
2.3关键词不能带特殊符号、个性化字词等没有行业通用性的内容
2.4关键词内容示例必须与关键词对应匹配
2.5关键词不能太过宽泛，需要具有限制性，例如：“内容”这个就太宽泛，不能审核通过

3.违规说明
除不能违反运营规范外，还不能违反以下规则，包括但不限于：
3.1不允许恶意诱导用户进行触发操作，以达到可向用户下发模板目的
3.2不允许恶意骚扰，下发对用户造成骚扰的模板
3.3不允许恶意营销，下发营销目的模板

4.处罚说明
根据违规情况给予相应梯度的处罚，一般处罚规则如下：
第一次违规，删除违规模板以示警告，
第二次违规，封禁接口7天，
第三次违规，封禁接口30天，
第四次违规，永久封禁接口
处罚结果及原因以站内信形式告知

Bug & Tip
tip: 微信6.5.2及以上版本支持模板功能。低于该版本将无法收到模板消息。

客服消息

接收消息和事件

在页面中使用 <contact-button/> 可以显示进入客服会话按钮。

当用户在客服会话发送消息（或进行某些特定的用户操作引发的事件推送时），微信服务器会将消息（或事件）的数据包（JSON或者XML格式）POST请求开发者填写的URL。开发者收到请求后可以使用发送客服消息接口进行异步回复。

微信服务器在将用户的消息发给小程序的开发者服务器地址（开发设置处配置）后，微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，如果在调试中，发现用户无法收到响应的消息，可以检查是否消息处理超时。关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime 排重。

服务器收到请求必须做出下述回复，这样微信服务器才不会对此作任何处理，并且不会发起重试，否则，将出现严重的错误提示。详见下面说明：

1、直接回复success（推荐方式）
2、直接回复空串（指字节长度为0的空字符串，而不是结构体中content字段的内容为空）
一旦遇到以下情况，微信都会在小程序会话中，向用户下发系统提示“该小程序客服暂时无法提供服务，请稍后再试”：

1、开发者在5秒内未回复任何内容
2、开发者回复了异常数据
如果开发者希望增强安全性，可以在开发者中心处开启消息加密，这样，用户发给小程序的消息以及小程序被动回复用户消息都会继续加密，详见消息加解密说明。

各消息类型的推送JSON、XML数据包结构如下。

文本消息

用户在客服会话中发送文本消息时将产生如下数据包：

XML 格式
<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1482048670</CreateTime>
   <MsgType><![CDATA[text]]></MsgType>
   <Content><![CDATA[this is a test]]></Content>
   <MsgId>1234567890123456</MsgId>
</xml>

JSON 格式
{
    "ToUserName": "toUser",//小程序的原始ID
    "FromUserName": "fromUser",//发送者的openid
    "CreateTime": 1482048670,//消息创建时间(整型）
    "MsgType": "text",//text
    "Content": "this is a test",/文本消息内容
    "MsgId": 1234567890123456//消息id，64位整型
}

 

图片消息

用户在客服会话中发送图片消息时将产生如下数据包：

XML 格式
<xml>
      <ToUserName><![CDATA[toUser]]></ToUserName>
      <FromUserName><![CDATA[fromUser]]></FromUserName>
      <CreateTime>1482048670</CreateTime>
      <MsgType><![CDATA[image]]></MsgType>
      <PicUrl><![CDATA[this is a url]]></PicUrl>
      <MediaId><![CDATA[media_id]]></MediaId>
      <MsgId>1234567890123456</MsgId>
</xml>

JSON 格式
{
    "ToUserName": "toUser",//小程序的原始ID
    "FromUserName": "fromUser",//发送者的openid
    "CreateTime": 1482048670,//消息创建时间(整型）
    "MsgType": "image",//image
    "PicUrl": "this is a url",//图片链接（由系统生成）
    "MediaId": "media_id",//图片消息媒体id，可以调用获取临时素材接口拉取数据
    "MsgId": 1234567890123456//消息id，64位整型
}

 

小程序卡片消息

用户在客服会话中发送小程序卡片消息时将产生如下数据包：

XML 格式
<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>
    <FromUserName><![CDATA[fromUser]]></FromUserName>
    <CreateTime>1482048670</CreateTime>
    <MsgType><![CDATA[miniprogrampage]]></MsgType>
    <MsgId>1234567890123456</MsgId>
    <Title><![CDATA[Title]]></Title>
    <AppId><![CDATA[AppId]]></AppId>
    <PagePath><![CDATA[PagePath]]></PagePath>
    <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>
    <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId>
</xml>
JSON 格式
{
    "ToUserName": "toUser",//小程序的原始ID
    "FromUserName": "fromUser",//发送者的openid
    "CreateTime": 1482048670,//消息创建时间(整型）
    "MsgType": "miniprogrampage",//miniprogrampage
    "MsgId": 1234567890123456,//消息id，64位整型
    "Title":"title",//标题
    "AppId":"appid",//小程序appid
    "PagePath":"path",//小程序页面路径
    "ThumbUrl":"",//封面图片的临时cdn链接
    "ThumbMediaId":""//封面图片的临时素材id
}

 

进入会话事件

用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包：

XML 格式
<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>  
    <FromUserName><![CDATA[fromUser]]></FromUserName>  
    <CreateTime>1482048670</CreateTime>  
    <MsgType><![CDATA[event]]></MsgType>  
    <Event><![CDATA[user_enter_tempsession]]></Event>  
    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom> 
</xml>
JSON 格式
{
    "ToUserName": "toUser",//小程序的原始ID
    "FromUserName": "fromUser",//发送者的openid
    "CreateTime": 1482048670,//事件创建时间(整型）
    "MsgType": "event",//event
    "Event": "user_enter_tempsession",//事件类型，user_enter_tempsession
    "SessionFrom": "sessionFrom"//开发者在客服会话按钮设置的sessionFrom参数
}

 

发送客服消息

当用户和小程序客服产生特定动作的交互时（具体动作列表请见下方说明），微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前修改为48小时）调用客服接口，通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。

目前允许的动作列表如下，不同动作触发后，允许的客服接口下发消息条数和下发时限不同。下发条数达到上限后，会收到错误返回码，具体请见返回码说明页：

用户动作 允许下发条数限制 下发时限
用户通过客服消息按钮进入会话 1条 1分钟
用户发送信息 5条 48小时
zebra stripes are neat $1

客服接口-发消息

http请求方式: POST
https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

各消息类型所需的JSON数据包如下：

发送文本消息
{
    "access_token"//(必要)调用接口凭证
    "touser":"OPENID",//(必要)普通用户(openid)
    "msgtype":"text",//(必要)消息类型，文本为text，图文链接为link
    "text":
    {
         "content":"Hello World"//(必要)文本消息内容
    }
}

发送图片消息
{
    "access_token"//(必要)调用接口凭证
    "touser":"OPENID",//(必要)普通用户(openid)
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"//(必要)发送的图片的媒体ID，通过新增素材接口上传图片文件获得
    }
}

发送图文链接
每次可以发送一个图文链接
{
    "access_token"//(必要)调用接口凭证
    "touser": "OPENID",//(必要)普通用户(openid)
    "msgtype": "link",
    "link": {
          "title": "Happy Day",//(必要)消息标题
          "description": "Is Really A Happy Day",//(必要)图文链接消息
          "url": "URL",//(必要)图文链接消息被点击后跳转的链接
          "thumb_url": "THUMB_URL"
    }
}

发送小程序卡片
{
    "access_token"//(必要)调用接口凭证
    "touser":"OPENID",//(必要)普通用户(openid)
    "msgtype":"miniprogrampage",
    "miniprogrampage":{
        "title":"title",
        "pagepath":"pagepath",//(必要)小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar
        "thumb_media_id":"thumb_media_id"//(必要)小程序消息卡片的封面， image类型的media_id，通过新增素材接口上传图片文件获得，建议大小为520*416
    }
}
返回码说明
-1  系统繁忙，此时请开发者稍候再试
0   请求成功
40001   获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的小程序调用接口
40002   不合法的凭证类型
40003   不合法的 OpenID，请开发者确认OpenID否是其他小程序的 OpenID
45015   回复时间超过限制
45047   客服接口下行条数超过上限
48001   api功能未授权，请确认小程序已获得该接口

 

转发消息

如果小程序设置了消息推送，普通微信用户向小程序客服发消息时，微信服务器会先将消息 POST 到开发者填写的 url 上，如果希望将消息转发到网页版客服工具，则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息，微信服务器收到响应后会把当次发送的消息转发至客服系统。

用户被客服接入以后，客服关闭会话以前，处于会话过程中时，用户发送的消息均会被直接转发至客服系统。当会话超过 30 分钟客服没有关闭时，微信服务器会自动停止转发至客服，而将消息恢复发送至开发者填写的 url 上。

用户在等待队列中时，用户发送的消息仍然会被推送至开发者填写的 url 上。

这里特别要注意，只针对微信用户发来的消息才进行转发，而对于其他事件（比如用户从小程序唤起客服会话）都不应该转接，否则客服在客服系统上就会看到一些无意义的消息了。

消息转发到网页版客服工具

开发者只在响应包中返回 MsgType 为 transfer_customer_service 的消息，微信服务器收到响应后就会把当次发送的消息转发至客服系统。

 <xml>
     <ToUserName><![CDATA[touser]]></ToUserName>
     <FromUserName><![CDATA[fromuser]]></FromUserName>
     <CreateTime>1399197672</CreateTime>
     <MsgType><![CDATA[transfer_customer_service]]></MsgType>
 </xml>

参数说明
参数  是否必须    描述
ToUserName  是   接收方帐号（收到的OpenID）
FromUserName    是   开发者微信号
CreateTime  是   消息创建时间 （整型）
MsgType 是   transfer_customer_service

 

临时素材接口

获取临时素材

小程序可以使用本接口获取客服消息内的临时素材（即下载临时的多媒体文件）。目前小程序仅支持下载图片文件。

接口调用请求说明
HTTP 请求方式: GET，HTTPS 调用
https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
请求示例（示例为通过curl命令获取多媒体文件）
curl -I -G “https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID”

参数说明
access_token//(必要)调用接口凭证
media_id//(必要)媒体文件ID

返回说明
正确情况下的返回 HTTP 头如下：

HTTP/1.1 200 OK
Connection: close
Content-Type: image/jpeg 
Content-disposition: attachment; filename="MEDIA_ID.jpg"
Date: Sun, 06 Jan 2013 10:20:18 GMT
Cache-Control: no-cache, must-revalidate
Content-Length: 339721
curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

如果返回的是视频消息素材，则内容如下：
{
 "video_url":DOWN_URL
}

错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：=
{
  "errcode":40007,
  "errmsg":"invalid media_id"
}

 

新增临时素材

小程序可以使用本接口把媒体文件（目前仅支持图片）上传到微信服务器，用户发送客服消息或被动回复用户消息。

接口调用请求说明
HTTP 请求方式：POST/FORM，HTTPS 调用

https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE
调用示例（使用curl命令，用FORM表单方式上传一个多媒体文件）：

curl -F media=@test.jpg “https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE”

参数说明
access_token//(必要)调用接口凭证
type//(必要)image
media//(必要)form-data中媒体文件标识，有filename、filelength、content-type等信息

返回说明
正确情况下的返回 JSON 数据包结果如下：
{
  "type":"TYPE",//image
  "media_id":"MEDIA_ID",//媒体文件上传后，获取标识
  "created_at":123456789//媒体文件上传时间戳
}

错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：
{
  "errcode":40004,
  "errmsg":"invalid media type"
}

 

客服输入状态

开发者可通过调用“客服输入状态接口”，返回客服当前输入状态给用户。

  • 此接口需要客服消息接口权限。
  • 如果不满足发送客服消息的触发条件，则无法下发输入状态。
  • 下发输入状态，需要客服之前30秒内跟用户有过消息交互。
  • 在输入状态中（持续15s），不可重复下发输入态。
  • 在输入状态中，如果向用户下发消息，会同时取消输入状态。

接口调用请求说明

http请求方式: POST
https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN

JSON数据包如下：
{
    "access_token"//调用接口凭证
    "touser":"OPENID",//普通用户(openid)
    "command":"Typing"//"Typing"：对用户下发“正在输入"状态；"CancelTyping"：取消对用户的”正在输入"状态
}

预期返回：
{
    "errcode":0,
    "errmsg":"ok"
}
返回码说明
45072   command字段取值不对
45080   下发输入状态，需要之前30秒内跟用户有过消息交互
45081   已经在输入状态，不可重复下发

 

转发

onShareAppMessage(options)

在 Page 中定义 onShareAppMessage 函数，设置该页面的转发信息。

  • 只有定义了此事件处理函数，右上角菜单才会显示 “转发” 按钮
  • 用户点击转发按钮的时候会调用
  • 此事件需要 return 一个 Object，用于自定义转发内容
Page({
  onShareAppMessage: function (res) {
    res.from//转发事件来源。button：页面内转发按钮；menu：右上角转发菜单
    res.target//如果 from 值是 button，则 target 是触发这次转发事件的 button，否则为 undefined
    return {
      title: '自定义转发标题',//转发标题,默认当前小程序名称
      path: '/page/user?id=123',//转发路径, 默认当前页面 path, 必须是以 / 开头的完整路径
      imageUrl//自定义图片路径，可以是本地文件路径、代码包文件路径或者网络图片路径，支持PNG及JPG，不传入 imageUrl 则使用默认截图。iOS 显示图片长宽比是 5:4，Android 显示图片长宽比是 215:168。高度超出部分会从底部裁剪。推荐使用 Android 图片长宽比，可保证图片在两个平台都完整显示，其中 iOS 底部会出现一小段白色
      success: function(res) { // 转发成功
          res.errMsg//shareAppMessage:ok 转发成功
          res.shareTickets//shareTicket 数组，每一项是一个 shareTicket ，对应一个转发对象
      },
      fail/complete: function(res) { // 转发失败
          res.errMsg//shareAppMessage:fail cancel   用户取消转发
          res.errMsg//shareAppMessage:fail (detail message) 转发失败，其中 detail message 为详细失败信息
      },
      complete: function(res) { // 转发结束
      }
    }
  }
})

wx.showShareMenu(OBJECT)

显示当前页面的转发按钮

wx.showShareMenu({
    withShareTicket: true//是否使用带 shareTicket 的转发详情
    success/fail/complete: function(res) { //接口调用成功/失败/结束的回调函数
    }
})

 

wx.hideShareMenu(OBJECT)

隐藏转发按钮

wx.hideShareMenu()

 

wx.updateShareMenu(OBJECT)

更新转发属性

wx.updateShareMenu({
    withShareTicket: true//是否使用带 shareTicket 的转发详情
    success/fail/complete: function(res) { //接口调用成功/失败/结束的回调函数
    }
})

 

wx.getShareInfo(OBJECT)

获取转发详细信息

wx.getShareInfo({
    shareTicket: true//(必要)shareTicket
    success/fail/complete: function(res) { //接口调用成功/失败/结束的回调函数
        res.errMsg//错误信息
        res.encryptedData//包括敏感数据在内的完整转发信息的加密数据，详细见加密数据解密算法
        res.iv//加密算法的初始向量，详细见加密数据解密算法
    }
})
encryptedData 解密后为一个 JSON 结构，包含字段如下：openGId //群对当前小程序的唯一 ID

 

Tip: 如需要展示群名称，可以使用开放数据组件

获取更多转发信息

通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息，例如群的标识。现在通过调用 wx.showShareMenu 并且设置 withShareTicket 为 true ，当用户将小程序转发到任一群聊之后，可以获取到此次转发的 shareTicket，此转发卡片在群聊中被其他用户打开时，可以在 App.onLaunch() 或 App.onShow 获取到另一个 shareTicket。这两步获取到的 shareTicket 均可通过 wx.getShareInfo() 接口可以获取到相同的转发信息。

页面内发起转发

通过给 button 组件设置属性 open-type=”share”，可以在用户点击按钮后触发 Page.onShareAppMessage() 事件，如果当前页面没有定义此事件，则点击后无效果。相关组件：button

使用指引

转发按钮，旨在帮助用户更流畅地与好友分享内容和服务。转发，应是用户自发的行为，且在需要时触手可及。开发者在使用时若遵从以下指引，会得到更佳的用户体验。

含义清晰：明确、一目了然的图形按钮，将为用户减少理解的时间。在我们的资源下载中心，你可以找到这样的按钮素材并直接使用。或者你可以根据自己业务的设计风格，灵活设计含义清晰的按钮的样式。当然，你也可以直接使用带文案的按钮，“转发给好友”，它也足够明确。
方便点击：按钮点击热区不宜过小，亦不宜过大。同时，转发按钮与其他按钮一样，热区也不宜过密，以免用户误操作。
按需出现：并非所有页面都适合放置转发按钮，涉及用户隐私的非公开内容，或可能打断用户完成当前操作体验的场景，该功能并不推荐使用。同时，由于转发过程中，我们将截取用户屏幕图像作为配图，因此，需要注意帮助用户屏蔽个人信息。
尊重意愿：理所当然，并非所有的用户，都喜欢与朋友分享你的小程序。因此，它不应该成为一个诱导或强制行为，如转发后才能解锁某项功能等。请注意，这类做法不仅不被推荐，还可能违反我们的《运营规范》，我们强烈建议你在使用前阅读这部分内容。
以上，我们陈列了最重要的几点，如果你有时间，可以完整浏览《设计指南》，相信会有更多的收获。

Bug & Tip

tip: 不自定义转发图片的情况下，默认会取当前页面，从顶部开始，高度为 80% 屏幕宽度的图像作为转发图片。
tip: 转发的调试支持请查看 普通转发的调试支持 和 带 shareTicket 的转发
tip: 只有转发到群聊中打开才可以获取到 shareTickets 返回值，单聊没有 shareTickets
tip: shareTicket 仅在当前小程序生命周期内有效
tip: 由于策略变动，小程序群相关能力进行调整，开发者可先使用wx.getShareInfo接口中的群ID进行功能开发。

获取二维码

通过后台接口可以获取小程序任意页面的二维码，扫描该二维码可以直接进入小程序对应的页面。目前微信支持两种二维码 : 小程序码，小程序二维码

获取小程序码

我们推荐生成并使用小程序码，它具有更好的辨识度。目前有两个接口可以生成小程序码，开发者可以根据自己的需要选择合适的接口。

接口A: 适用于需要的码数量较少的业务场景 接口地址：

https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN

获取 access_token 详见文档

POST 参数说明
{
    "path"//不能为空，最大长度 128 字节
    "width"//默认430，二维码的宽度
    "auto_color"//默认false，自动配置线条颜色，如果颜色依然是黑色，则说明不建议配置主色调
    "line_color"//默认{"r":"0","g":"0","b":"0"}   auth_color 为 false 时生效，使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}
}

 

注意：通过该接口生成的小程序码，永久有效，数量限制见文末说明，请谨慎使用。用户扫描该码进入小程序后，将直接进入 path 对应的页面。

接口B：适用于需要的码数量极多，或仅临时使用的业务场景

接口地址：

https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN
获取 access_token 详见文档

POST 参数说明
{
    "scene"//最大32个可见字符，只支持数字，大小写英文以及部分特殊字符：!#$&'()*+,/:;=?@-._~，其它字符请自行编码为合法字符（因不支持%，中文无法使用 urlencode 处理，请使用其他编码方式）
    "page"//必须是已经发布的小程序页面，例如 "pages/index/index" ,根路径前不要填加'/',不能携带参数（参数请放在scene字段里），如果不填写这个字段，默认跳主页面
    "width"//默认430，二维码的宽度
    "auto_color"//默认false，自动配置线条颜色，如果颜色依然是黑色，则说明不建议配置主色调
    "line_color"//默认{"r":"0","g":"0","b":"0"}   auth_color 为 false 时生效，使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}
}

 

注意：通过该接口生成的小程序码，永久有效，数量暂无限制。用户扫描该码进入小程序后，开发者需在对应页面获取的码中 scene 字段的值，再做处理逻辑。使用如下代码可以获取到二维码中的 scene 字段的值。调试阶段可以使用开发工具的条件编译自定义参数 scene=xxxx 进行模拟，开发工具模拟时的 scene 的参数值需要进行 urlencode

// 这是首页的 js
Page({
  onLoad: function(options) {
    // options 中的 scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene
    var scene = decodeURIComponent(options.scene)
  }
})

 

获取小程序二维码

接口C：适用于需要的码数量较少的业务场景

接口地址：

https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN
获取 access_token 详见文档

POST 参数说明
{
    "path": "pages/index?query=1", //不能为空，最大长度 128 字节
    "width": 430//二维码的宽度
}

 

注意：
1.通过该接口生成的小程序二维码，永久有效，数量限制见文末说明，请谨慎使用。用户扫描该码进入小程序后，将直接进入 path 对应的页面。
2.pages/index 需要在 app.json 的 pages 中定义

Bug & Tip
tip：通过该接口，仅能生成已发布的小程序的二维码。
tip：可以在开发者工具预览时生成开发版的带参二维码。
tip：接口A加上接口C，总共生成的码数量限制为100,000，请谨慎调用。
tip: POST 参数需要转成 json 字符串，不支持 form 表单提交。
tip: auto_color line_color 参数仅对小程序码生效。

收货地址

wx.chooseAddress(OBJECT)

调起用户编辑收货地址原生界面，并在编辑完成后返回用户选择的地址。
需要用户授权 scope.address

wx.chooseAddress({
  success: function (res) {
      res.errMsg//调用结果
      res.userName//收货人姓名
      res.postalCode//邮编
      res.provinceName//国标收货地址第一级地址
      res.cityName//国标收货地址第二级地址
      res.countyName国标收货地址第三级地址
      res.detailInfo//详细收货地址信息
      res.nationalCode//收货地址国家码
      res.telNumber//收货人手机号码
  },
  fail/complete: function(res){//接口调用失败/结束的回调函数
  }
})

 

卡券

wx.addCard(OBJECT)

批量添加卡券

wx.addCard({
  cardList: [//(必要)需要添加的卡券列表，列表内对象说明请参见请求对象说明
    {
      cardId: '',//卡券 Id
      cardExt: '{//卡券的扩展参数
         "code": "",//用户领取的 code，仅自定义 code 模式的卡券须填写，非自定义 code 模式卡券不可填写，详情
         "openid": "",//指定领取者的openid，只有该用户能领取。 bind_openid 字段为 true 的卡券必须填写，bind_openid 字段为 false 不可填写。
         "timestamp": "", //(必要)时间戳，东八区时间,UTC+8，单位为秒
         "nonce_str":""//随机字符串，由开发者设置传入，加强安全性（若不填写可能被重放请求）。随机字符串，不长于 32 位。推荐使用大小写字母和数字，不同添加请求的 nonce_str 须动态生成，若重复将会导致领取失败。
         "fixed_begintimestamp":""//卡券在第三方系统的实际领取时间，为东八区时间戳（UTC+8,精确到秒）。当卡券的有效期类为 DATE_TYPE_FIX_TERM 时专用，标识卡券的实际生效时间，用于解决商户系统内起始时间和领取微信卡券时间不同步的问题。
         "outer_str":""//领取渠道参数，用于标识本次领取的渠道值
         "signature":""//(必要)签名，商户将接口列表中的参数按照指定方式进行签名,签名方式使用 SHA1，具体签名方案参见：卡券签名
      }'
    }, {
      cardId: '',
      cardExt: '{"code": "", "openid": "", "timestamp": "", "signature":""}'
    }
  ],
  success: function(res) {
    res.errMsg//addCard:ok  添加卡券成功
    res.cardList //卡券添加结果
    res.cardList.code//加密 code，为用户领取到卡券的code加密后的字符串，解密请参照：code 解码接口
    res.cardList.cardId//用户领取到卡券的Id
    res.cardList.cardExt//用户领取到卡券的扩展参数，与调用时传入的参数相同
    res.cardList.isSuccess//是否成功
  },
  fail: function(res){
    res.errMsg//addCard:fail cancel 用户取消添加卡券
    res.errMsg//addCard:fail (detail message)   添加卡券失败，其中 detail message 为后台返回的详细失败原因
  }
})

 

wx.openCard(OBJECT)

查看微信卡包中的卡券。

wx.openCard({
  cardList: [//(必要)需要打开的卡券列表，列表内参数详见openCard 请求对象说明
    {
      cardId: '',//需要打开的卡券 Id
      code: ''//由 addCard 的返回对象中的加密 code 通过解密后得到，解密请参照：code 解码接口
    }, {
      cardId: '',
      code: ''
    }
  ],
  success/fail/complete: function(res) {//接口调用成功/失败/结束的回调函数
  }
})

 

Tip
tip: 目前只有认证小程序才能使用卡券接口，可参考指引进行认证。
tip: 了解更多信息，请查看微信卡券接口文档

设置

wx.openSetting(OBJECT)

调起客户端小程序设置界面，返回用户设置的操作结果。
注：设置界面只会出现小程序已经向用户请求过的权限。

wx.openSetting({
  success: (res) => {
    /*
     * res.authSetting = {//用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: function(res) {//接口调用成功/失败的回调函数
  }
})

 

wx.getSetting(OBJECT)

获取用户的当前设置。
注：返回值中只会出现小程序已经向用户请求过的权限。

wx.getSetting({
  success: (res) => {
    /*
     * res.authSetting = {//用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: function(res) {//接口调用成功/失败的回调函数
  }
})

 

微信运动

wx.getWeRunData(OBJECT)

获取用户过去三十天微信运动步数，需要先调用 wx.login 接口。
需要用户授权 scope.werun

wx.getWeRunData({
    success(res) {
        res.errMsg  //调用结果
        res.iv//加密算法的初始向量，详细见加密数据解密算法
        const encryptedData = res.encryptedData//包括敏感数据在内的完整用户信息的加密数据，详细见加密数据解密算法

    }
})
{
    "stepInfoList": [
        {
            "timestamp": 1445866601,
            "step": 100
        },
        {
            "timestamp": 1445866602,
            "step": 100
        }
    ]
}

 

打开小程序

wx.navigateToMiniProgram(OBJECT)

打开同一公众号下关联的另一个小程序

wx.navigateToMiniProgram({
  appId: '',<span class="hljs-comment">//(必要)要打开的小程序 appId</span>
  path: 'pages/index/index?id=123',<span class="hljs-comment">//打开的页面路径，如果为空则打开首页</span>
  extraData: {<span class="hljs-comment">//需要传递给目标小程序的数据，目标小程序可在 App.onLaunch()，App.onShow() 中获取到这份数据</span>
    foo: 'bar'
  },
  envVersion: 'develop',<span class="hljs-comment">//要打开的小程序版本，有效值 develop（开发版），trial（体验版），release（正式版） ，仅在当前小程序为开发版或体验版时此参数有效；如果当前小程序是体验版或正式版，则打开的小程序必定是正式版。默认值 release</span>
  success/<span class="hljs-keyword">fail</span>/complete(res) {<span class="hljs-comment">//接口调用成功/失败/结束的回调函数</span>
      res.errMsg<span class="hljs-comment">//调用结果</span>
    <span class="hljs-comment">// 打开成功</span>
  }
})

Bug & Tip
tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序，但是开发者工具会校验本次调用跳转是否成功详情
tip: 开发者工具上支持被跳转的小程序处理接收参数的调试详情
tip: 只有同一公众号下的关联的小程序之间才可相互跳转 详情

wx.navigateBackMiniProgram(OBJECT)

返回到上一个小程序，只有在当前小程序是被其他小程序打开时可以调用成功

wx.navigateBackMiniProgram({
  extraData: {<span class="hljs-comment">//需要返回给上一个小程序的数据，上一个小程序可在 App.onShow() 中获取到这份数据。详情</span>
    foo: 'bar'
  },
  success/<span class="hljs-keyword">fail</span>/complete(res) {<span class="hljs-comment">//接口调用成功/失败/结束的回调函数</span>
      res.errMsg<span class="hljs-comment">//调用结果</span>
    <span class="hljs-comment">// 打开成功</span>
  }
})

获取发票抬头

wx.chooseInvoiceTitle(OBJECT)

选择用户的发票抬头。
需要用户授权 scope.invoiceTitle

wx.chooseInvoiceTitle({
  success(res) {
    res.<span class="hljs-keyword">type</span><span class="hljs-comment">//抬头类型（0：单位，1：个人）</span>
    res.title<span class="hljs-comment">//抬头名称</span>
    res.taxNumber<span class="hljs-comment">//抬头税号</span>
    res.companyAddress<span class="hljs-comment">//单位地址</span>
    res.telephone<span class="hljs-comment">//手机号码</span>
    res.bankName<span class="hljs-comment">//银行名称</span>
    res.bankAccount<span class="hljs-comment">//银行账号</span>
    res.errMsg<span class="hljs-comment">//接口调用结果</span>
  },
  <span class="hljs-keyword">fail</span>/complete(res) {<span class="hljs-comment">//接口调用失败/结束的回调函数</span>
  }
})

生物认证

wx.checkIsSupportSoterAuthentication(OBJECT)

获取本机支持的 SOTER 生物认证方式

wx.checkIsSupportSoterAuthentication({
    success(res) {
        res.errMsg//接口调用结果
        res.supportMode//该设备支持的可被SOTER识别的生物识别方式别方式
        res.supportMode = []//不具备任何被SOTER支持的生物识别方式
        res.supportMode = ['fingerPrint'] //只支持指纹识别
        res.supportMode = ['fingerPrint', 'facial'] //支持指纹识别和人脸识别
    },
    fail/complete(res) {//接口调用失败/结束的回调函数
    }
})

 

赞(0)
版权归原作者所有，如有侵权请告知。达维营-前端网 » 小程序文档整理之 — API（开放接口）

相关推荐

评论 抢沙发

取消

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
2017 年 7 月
一 二 三 四 五 六 日
 123
45678910
11121314151617
18192021222324
252627282930  

热门标签

JQuery (19)Javascript (18)git (16)IntelliJ Idea (15)gulp (13)git教程 (10)nodejs (7)composer (7)phpstorm (7)vue (7)ios (6)测试 (6)laravel (6)键盘 (6)uniapp (6)字体 (5)js (5)动画 (5)css (5)ajax (5)seajs (5)zepto (5)maven (5)requirejs (5)redis (5)插件 (4)input (4)优化 (4)idea (4)curl (4)