1
This commit is contained in:
302
_DEL/wechat-miniprogram/steering/server-api.md
Normal file
302
_DEL/wechat-miniprogram/steering/server-api.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# 服务端 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
|
||||
Reference in New Issue
Block a user