189 lines
4.0 KiB
Markdown
189 lines
4.0 KiB
Markdown
# QR码API使用说明
|
||
|
||
## 概述
|
||
|
||
QR码API已经升级为接收JSON格式的请求数据，提供更好的类型安全和扩展性。
|
||
|
||
## API接口说明
|
||
|
||
### 1. 生成加密二维码
|
||
|
||
**接口地址：** `POST /api/qr-code/create-encrypted-qr-code`
|
||
|
||
**请求格式：** JSON
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"data": "用户ID:12345",
|
||
"width": 200,
|
||
"height": 200,
|
||
"expireMinutes": 30,
|
||
"businessType": "LOGIN"
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `data` (必填): 要加密的数据
|
||
- `width` (可选): 二维码宽度，默认200，范围50-1000
|
||
- `height` (可选): 二维码高度，默认200，范围50-1000
|
||
- `expireMinutes` (可选): 过期时间（分钟），默认30，范围1-1440
|
||
- `businessType` (可选): 业务类型
|
||
|
||
### 2. 解密二维码数据
|
||
|
||
**接口地址：** `POST /api/qr-code/decrypt-qr-data`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"token": "abc123def456",
|
||
"encryptedData": "encrypted_data_string"
|
||
}
|
||
```
|
||
|
||
### 3. 验证并解密二维码内容
|
||
|
||
**接口地址：** `POST /api/qr-code/verify-and-decrypt-qr`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"qrContent": "qr_content_string"
|
||
}
|
||
```
|
||
|
||
### 4. 验证并解密二维码内容（返回完整结果）
|
||
|
||
**接口地址：** `POST /api/qr-code/verify-and-decrypt-qr-with-type`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"qrContent": "qr_content_string"
|
||
}
|
||
```
|
||
|
||
### 5. 生成业务加密二维码
|
||
|
||
**接口地址：** `POST /api/qr-code/create-business-encrypted-qr-code`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"data": "订单ID:ORDER123",
|
||
"businessKey": "store_key_123",
|
||
"width": 200,
|
||
"height": 200,
|
||
"expireMinutes": 30,
|
||
"businessType": "ORDER"
|
||
}
|
||
```
|
||
|
||
### 6. 门店核销二维码
|
||
|
||
**接口地址：** `POST /api/qr-code/verify-business-qr`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"qrContent": "qr_content_string",
|
||
"businessKey": "store_key_123"
|
||
}
|
||
```
|
||
|
||
### 7. 使token失效
|
||
|
||
**接口地址：** `POST /api/qr-code/invalidate-token`
|
||
|
||
**请求示例：**
|
||
```json
|
||
{
|
||
"token": "abc123def456"
|
||
}
|
||
```
|
||
|
||
## GET接口（保持不变）
|
||
|
||
以下GET接口保持原有的@RequestParam方式：
|
||
|
||
### 生成普通二维码
|
||
`GET /api/qr-code/create-qr-code?data=要编码的数据&size=200x200`
|
||
|
||
### 生成加密二维码图片流
|
||
`GET /api/qr-code/create-encrypted-qr-image?data=要加密的数据&size=200x200&expireMinutes=30&businessType=LOGIN`
|
||
|
||
**参数说明：**
|
||
- `data` (必填): 要加密的数据
|
||
- `size` (可选): 二维码尺寸，格式：宽x高，默认200x200
|
||
- `expireMinutes` (可选): 过期时间（分钟），默认30
|
||
- `businessType` (可选): 业务类型，如LOGIN、ORDER等
|
||
|
||
### 检查token是否有效
|
||
`GET /api/qr-code/check-token?token=abc123def456`
|
||
|
||
## 错误处理
|
||
|
||
API现在包含完整的参数验证，会返回具体的错误信息：
|
||
|
||
**验证失败示例：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "数据不能为空",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**常见验证错误：**
|
||
- "数据不能为空"
|
||
- "宽度不能小于50像素"
|
||
- "宽度不能大于1000像素"
|
||
- "过期时间不能小于1分钟"
|
||
- "过期时间不能大于1440分钟"
|
||
- "token不能为空"
|
||
- "业务密钥不能为空"
|
||
|
||
## 前端调用示例
|
||
|
||
### JavaScript/Axios
|
||
```javascript
|
||
// 生成加密二维码
|
||
const response = await axios.post('/api/qr-code/create-encrypted-qr-code', {
|
||
data: '用户ID:12345',
|
||
width: 200,
|
||
height: 200,
|
||
expireMinutes: 30,
|
||
businessType: 'LOGIN'
|
||
});
|
||
|
||
console.log(response.data);
|
||
```
|
||
|
||
### jQuery
|
||
```javascript
|
||
$.ajax({
|
||
url: '/api/qr-code/create-encrypted-qr-code',
|
||
type: 'POST',
|
||
contentType: 'application/json',
|
||
data: JSON.stringify({
|
||
data: '用户ID:12345',
|
||
width: 200,
|
||
height: 200,
|
||
expireMinutes: 30,
|
||
businessType: 'LOGIN'
|
||
}),
|
||
success: function(response) {
|
||
console.log(response);
|
||
}
|
||
});
|
||
```
|
||
|
||
## 升级说明
|
||
|
||
1. **向下兼容性：** GET接口保持不变，现有的GET请求不受影响
|
||
2. **类型安全：** JSON格式提供更好的类型检查和验证
|
||
3. **扩展性：** 新的DTO结构便于后续添加新字段
|
||
4. **错误处理：** 提供更详细和友好的错误信息
|
||
5. **功能增强：** `create-encrypted-qr-image`接口现在支持`businessType`参数
|