303 lines
6.6 KiB
Markdown
303 lines
6.6 KiB
Markdown
# 服务端 API
|
||
|
||
> 官方文档：https://developers.weixin.qq.com/miniprogram/dev/api-backend/
|
||
|
||
服务端 API 是小程序后端服务器调用微信服务器的 HTTP 接口。
|
||
|
||
## access_token
|
||
|
||
几乎所有服务端 API 都需要 access_token。
|
||
|
||
```
|
||
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"access_token": "ACCESS_TOKEN",
|
||
"expires_in": 7200
|
||
}
|
||
```
|
||
|
||
**注意事项**：
|
||
- 有效期 2 小时，需要定时刷新并缓存
|
||
- 每日调用上限有限制
|
||
- 多服务器部署时需要中控服务器统一管理 access_token
|
||
- 刷新 access_token 会使旧的立即失效
|
||
|
||
## 登录 — code2Session
|
||
|
||
```
|
||
GET https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"openid": "OPENID",
|
||
"session_key": "SESSION_KEY",
|
||
"unionid": "UNIONID",
|
||
"errcode": 0,
|
||
"errmsg": "ok"
|
||
}
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| openid | 用户唯一标识（同一小程序内唯一） |
|
||
| session_key | 会话密钥（用于解密用户数据） |
|
||
| unionid | 用户在开放平台的唯一标识（需绑定开放平台） |
|
||
|
||
**安全要求**：
|
||
- `session_key` 不能下发到前端
|
||
- `js_code` 只能使用一次
|
||
- 该接口不需要 access_token
|
||
|
||
## 手机号
|
||
|
||
### 获取手机号（新版，推荐）
|
||
|
||
前端通过 `<button open-type="getPhoneNumber">` 获取 code，后端用 code 换取手机号：
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"code": "动态令牌code"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"errcode": 0,
|
||
"errmsg": "ok",
|
||
"phone_info": {
|
||
"phoneNumber": "13800138000",
|
||
"purePhoneNumber": "13800138000",
|
||
"countryCode": "86",
|
||
"watermark": {
|
||
"timestamp": 1637744274,
|
||
"appid": "APPID"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 旧版解密方式（不推荐）
|
||
|
||
使用 session_key + iv 解密 encryptedData，获取手机号。
|
||
|
||
## 小程序码
|
||
|
||
### 获取不限制的小程序码（推荐）
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"scene": "id=123",
|
||
"page": "pages/index/index",
|
||
"check_path": true,
|
||
"env_version": "release",
|
||
"width": 430,
|
||
"auto_color": false,
|
||
"line_color": {"r": 0, "g": 0, "b": 0},
|
||
"is_hyaline": false
|
||
}
|
||
```
|
||
|
||
- `scene` 最大 32 个可见字符
|
||
- 返回二进制图片数据（Content-Type: image/jpeg 或 image/png）
|
||
- 数量不限制
|
||
|
||
### 获取小程序码（有限制）
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"path": "pages/index/index?id=123",
|
||
"width": 430
|
||
}
|
||
```
|
||
|
||
- `path` 可带参数，最大 128 字节
|
||
- 总数限制 10 万个
|
||
|
||
### 获取小程序二维码（有限制）
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"path": "pages/index/index?id=123",
|
||
"width": 430
|
||
}
|
||
```
|
||
|
||
- 总数限制 10 万个
|
||
|
||
## 订阅消息
|
||
|
||
### 发送订阅消息
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"touser": "OPENID",
|
||
"template_id": "TEMPLATE_ID",
|
||
"page": "pages/index/index",
|
||
"miniprogram_state": "formal",
|
||
"lang": "zh_CN",
|
||
"data": {
|
||
"thing1": { "value": "订单已发货" },
|
||
"time2": { "value": "2025-01-01 12:00" },
|
||
"character_string3": { "value": "SF1234567890" }
|
||
}
|
||
}
|
||
```
|
||
|
||
**前端需先请求用户授权**：
|
||
```javascript
|
||
wx.requestSubscribeMessage({
|
||
tmplIds: ['TEMPLATE_ID'],
|
||
success(res) {
|
||
// res[TEMPLATE_ID] === 'accept' 表示用户同意
|
||
}
|
||
})
|
||
```
|
||
|
||
## 客服消息
|
||
|
||
### 发送客服消息
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
|
||
|
||
// 文本消息
|
||
{
|
||
"touser": "OPENID",
|
||
"msgtype": "text",
|
||
"text": { "content": "Hello" }
|
||
}
|
||
|
||
// 图片消息
|
||
{
|
||
"touser": "OPENID",
|
||
"msgtype": "image",
|
||
"image": { "media_id": "MEDIA_ID" }
|
||
}
|
||
|
||
// 小程序卡片
|
||
{
|
||
"touser": "OPENID",
|
||
"msgtype": "miniprogrampage",
|
||
"miniprogrampage": {
|
||
"title": "标题",
|
||
"pagepath": "pages/index/index",
|
||
"thumb_media_id": "MEDIA_ID"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 内容安全
|
||
|
||
### 文本内容安全检测
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"content": "待检测文本",
|
||
"version": 2,
|
||
"scene": 1,
|
||
"openid": "OPENID"
|
||
}
|
||
```
|
||
|
||
scene 值：1-社交日志 2-评论 3-论坛 4-社交日志
|
||
|
||
### 图片内容安全检测
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/img_sec_check?access_token=ACCESS_TOKEN
|
||
|
||
// multipart/form-data 上传图片
|
||
```
|
||
|
||
## 数据分析
|
||
|
||
```
|
||
// 获取日访问数据
|
||
POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN
|
||
{ "begin_date": "20250101", "end_date": "20250101" }
|
||
|
||
// 获取用户画像
|
||
POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN
|
||
{ "begin_date": "20250101", "end_date": "20250107" }
|
||
```
|
||
|
||
## URL Scheme / URL Link
|
||
|
||
### 生成 URL Scheme（用于短信/邮件等外部跳转）
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/generatescheme?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"jump_wxa": {
|
||
"path": "pages/index/index",
|
||
"query": "id=123",
|
||
"env_version": "release"
|
||
},
|
||
"is_expire": true,
|
||
"expire_type": 0,
|
||
"expire_time": 1672502400
|
||
}
|
||
```
|
||
|
||
### 生成 URL Link（用于短信/邮件等外部跳转）
|
||
|
||
```
|
||
POST https://api.weixin.qq.com/wxa/generate_urllink?access_token=ACCESS_TOKEN
|
||
|
||
{
|
||
"path": "pages/index/index",
|
||
"query": "id=123",
|
||
"is_expire": true,
|
||
"expire_type": 0,
|
||
"expire_time": 1672502400,
|
||
"env_version": "release"
|
||
}
|
||
```
|
||
|
||
## 常见错误码
|
||
|
||
| errcode | 说明 |
|
||
|---------|------|
|
||
| -1 | 系统繁忙 |
|
||
| 0 | 请求成功 |
|
||
| 40001 | access_token 无效或过期 |
|
||
| 40013 | 不合法的 AppID |
|
||
| 40029 | 不合法的 code（已使用或过期） |
|
||
| 40125 | 不合法的 appsecret |
|
||
| 41002 | 缺少 appid |
|
||
| 41004 | 缺少 appsecret |
|
||
| 42001 | access_token 过期 |
|
||
| 45009 | 调用超过频率限制 |
|
||
| 45011 | API 调用太频繁 |
|
||
| 48001 | API 未授权 |
|
||
| 61024 | 该 code 已被使用 |
|
||
|
||
## 在线查询
|
||
|
||
如需查看某个具体服务端 API 的完整参数，可抓取：
|
||
- 服务端 API 总览：https://developers.weixin.qq.com/miniprogram/dev/api-backend/
|
||
- 登录：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/login/auth.code2Session.html
|
||
- 手机号：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/phonenumber/phonenumber.getPhoneNumber.html
|
||
- 小程序码：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/qr-code/wxacode.getUnlimited.html
|
||
- 订阅消息：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/subscribe-message/subscribeMessage.send.html
|