# 服务端 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