mp-java/docs/QR_CODE_API_USAGE.md

QR码API使用说明

概述

QR码API已经升级为接收JSON格式的请求数据，提供更好的类型安全和扩展性。

API接口说明

1. 生成加密二维码

接口地址： POST /api/qr-code/create-encrypted-qr-code

请求格式： 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

请求示例：

{
  "token": "abc123def456",
  "encryptedData": "encrypted_data_string"
}

3. 验证并解密二维码内容

接口地址： POST /api/qr-code/verify-and-decrypt-qr

请求示例：

{
  "qrContent": "qr_content_string"
}

4. 验证并解密二维码内容（返回完整结果）

接口地址： POST /api/qr-code/verify-and-decrypt-qr-with-type

请求示例：

{
  "qrContent": "qr_content_string"
}

5. 生成业务加密二维码

接口地址： POST /api/qr-code/create-business-encrypted-qr-code

请求示例：

{
  "data": "订单ID:ORDER123",
  "businessKey": "store_key_123",
  "width": 200,
  "height": 200,
  "expireMinutes": 30,
  "businessType": "ORDER"
}

6. 门店核销二维码

接口地址： POST /api/qr-code/verify-business-qr

请求示例：

{
  "qrContent": "qr_content_string",
  "businessKey": "store_key_123"
}

7. 使token失效

接口地址： POST /api/qr-code/invalidate-token

请求示例：

{
  "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现在包含完整的参数验证，会返回具体的错误信息：

验证失败示例：

{
  "code": 500,
  "message": "数据不能为空",
  "data": null
}

常见验证错误：

• "数据不能为空"
• "宽度不能小于50像素"
• "宽度不能大于1000像素"
• "过期时间不能小于1分钟"
• "过期时间不能大于1440分钟"
• "token不能为空"
• "业务密钥不能为空"

前端调用示例

JavaScript/Axios

// 生成加密二维码
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

$.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参数