forked from erp-dev/erp
165 lines
3.6 KiB
Markdown
165 lines
3.6 KiB
Markdown
# 消息发送 API
|
||
|
||
这组 API 用于对外主动发送企业微信应用消息。
|
||
|
||
当前提供两个接口：
|
||
|
||
- `POST /api/message/send`：发送文本消息
|
||
- `POST /api/message/send/news`：发送单篇图文消息，可同时投递到多个 `agent_id`
|
||
|
||
## 鉴权
|
||
|
||
仅这组消息发送 API 需要固定 `Authorization` 请求头。
|
||
|
||
服务端读取环境变量：
|
||
|
||
- `MESSAGE_API_AUTHORIZATION`
|
||
|
||
默认值：
|
||
|
||
- `hophopkk`
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
Authorization: hophopkk
|
||
Content-Type: application/json
|
||
```
|
||
|
||
鉴权失败时返回：
|
||
|
||
```json
|
||
{
|
||
"detail": "Invalid Authorization header"
|
||
}
|
||
```
|
||
|
||
HTTP 状态码：`401 Unauthorized`
|
||
|
||
## 发送文本消息
|
||
|
||
### 请求
|
||
|
||
`POST /api/message/send`
|
||
|
||
```json
|
||
{
|
||
"agent_id": 1000007,
|
||
"content": "库存盘点将在 18:00 开始",
|
||
"user_ids": ["zhangsan", "lisi"]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `agent_id` | integer | 是 | 企业微信应用 ID |
|
||
| `content` | string | 是 | 文本内容，1-2048 字节 |
|
||
| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"errcode": 0,
|
||
"errmsg": "ok"
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
|
||
```bash
|
||
curl -X POST 'http://localhost:8198/api/message/send' \
|
||
-H 'Authorization: hophopkk' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"agent_id": 1000007,
|
||
"content": "库存盘点将在 18:00 开始",
|
||
"user_ids": ["zhangsan", "lisi"]
|
||
}'
|
||
```
|
||
|
||
## 发送图文消息
|
||
|
||
### 请求
|
||
|
||
`POST /api/message/send/news`
|
||
|
||
```json
|
||
{
|
||
"agent_ids": [1000007, 1000008],
|
||
"title": "销售日报",
|
||
"description": "点击查看今日各区域销售汇总",
|
||
"url": "https://example.com/reports/daily-sales",
|
||
"image_url": "https://example.com/static/daily-sales-cover.png",
|
||
"user_ids": ["zhangsan"]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `agent_ids` | integer[] | 是 | 目标应用 ID 列表，至少 1 个 |
|
||
| `title` | string | 是 | 图文标题，1-128 字符 |
|
||
| `description` | string | 是 | 图文描述，1-512 字符 |
|
||
| `url` | string | 是 | 点击跳转链接 |
|
||
| `image_url` | string | 是 | 封面图片 URL，直接映射到企业微信 `picurl` |
|
||
| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
|
||
|
||
### 成功响应
|
||
|
||
至少一个 `agent_id` 发送成功时返回 `200`，并带每个应用的发送结果：
|
||
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"agent_id": 1000007,
|
||
"ok": true,
|
||
"response": {
|
||
"errcode": 0,
|
||
"errmsg": "ok"
|
||
},
|
||
"error": null
|
||
},
|
||
{
|
||
"agent_id": 1000008,
|
||
"ok": false,
|
||
"response": null,
|
||
"error": "agent not found"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
如果所有 `agent_id` 都失败，则返回 `502 Bad Gateway`：
|
||
|
||
```json
|
||
{
|
||
"detail": "All agent sends failed"
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
|
||
```bash
|
||
curl -X POST 'http://localhost:8198/api/message/send/news' \
|
||
-H 'Authorization: hophopkk' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"agent_ids": [1000007, 1000008],
|
||
"title": "销售日报",
|
||
"description": "点击查看今日各区域销售汇总",
|
||
"url": "https://example.com/reports/daily-sales",
|
||
"image_url": "https://example.com/static/daily-sales-cover.png",
|
||
"user_ids": ["zhangsan"]
|
||
}'
|
||
```
|
||
|
||
## 发布建议
|
||
|
||
- 如果要对外给第三方系统调用，至少同步交付这份文档和环境变量名 `MESSAGE_API_AUTHORIZATION`
|
||
- 当前是固定密钥模式，适合内网或受控系统对接，不适合开放互联网暴露
|
||
- 如果后续要接入更多对外方，建议升级为签名、时间戳或短期 token 模式 |