发布时间: 阅读量

(Untitled)

API接口文档

版本信息

1. 新增卡批次

1.1 基本信息

  • 接口名称: 新增卡批次
  • 接口描述: 新增社保卡批次信息，用于批量制卡管理
  • 请求URL: /batch/add
  • 请求方式: POST
  • 接口权限: 无需权限（对外开放）
  • Content-Type: application/json

1.2 请求参数

Body参数（JSON格式）

参数名 类型 必填 说明 示例值
batchNo String 是 批次号 "BATCH202411120001"
station String 是 银行网点 "中国银行北京分行"
num Long 是 制卡数量 1000
remark String 否 备注信息 "2024年11月批次"

1.3 返回参数

参数名 类型 说明
code Integer 响应状态码（200成功，500失败）
msg String 响应消息
data Integer 受影响的行数（成功为1）

1.4 请求示例

curl -X POST "http://localhost:8080/batch/add" \
  -H "Content-Type: application/json" \
  -d '{
    "batchNo": "BATCH202411120001",
    "station": "中国银行北京分行",
    "num": 1000,
    "remark": "2024年11月批次"
  }'

1.5 响应示例

成功响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": 1
}

失败响应:

{
  "code": 500,
  "msg": "操作失败",
  "data": null
}

1.6 状态码说明

状态码 说明
200 请求成功
500 服务器内部错误
400 请求参数错误

1.7 业务规则

  1. 批次号（batchNo）应保持唯一性
  2. 制卡数量（num）必须大于0
  3. 银行网点（station）不能为空
  4. 系统会自动记录创建时间和创建人信息

2. 卡状态变更

2.1 基本信息

  • 接口名称: 卡状态变更
  • 接口描述: 更新社保卡状态，支持激活、挂失、注销等操作
  • 请求URL: /card/updateByType
  • 请求方式: GET
  • 接口权限: 无需权限（对外开放）

2.2 请求参数

Query参数

参数名 类型 必填 说明 示例值
cardNum String 是 卡号 "6228480402564890018"
type Integer 是 状态类型
1-待激活
2-激活
3-挂失
4-注销		 2

2.3 返回参数

该接口返回类型为void，无返回值。操作成功则正常返回，失败则抛出异常。

2.4 请求示例

# 激活卡片
curl -X GET "http://localhost:8080/card/updateByType?cardNum=6228480402564890018&type=2"

# 挂失卡片
curl -X GET "http://localhost:8080/card/updateByType?cardNum=6228480402564890018&type=3"

# 注销卡片
curl -X GET "http://localhost:8080/card/updateByType?cardNum=6228480402564890018&type=4"

Java示例:

// 激活卡片
cardInfoController.updateByType("6228480402564890018", 2);

// 挂失卡片
cardInfoController.updateByType("6228480402564890018", 3);

// 注销卡片
cardInfoController.updateByType("6228480402564890018", 4);

2.5 响应示例

成功响应:

HTTP/1.1 200 OK
(无返回内容)

失败响应:

{
  "code": 500,
  "msg": "卡号不存在或状态变更失败"
}

2.6 状态码说明

状态码 说明
200 请求成功
400 请求参数错误（卡号或状态类型不合法）
404 卡号不存在
500 服务器内部错误

2.7 状态类型说明

type值 状态名称 说明
1 待激活 卡片已制作但未激活
2 激活 卡片已激活，可正常使用
3 挂失 卡片已挂失，暂停使用
4 注销 卡片已注销，永久停用

2.8 业务规则

  1. 卡号（cardNum）必须存在于系统中
  2. 状态变更需遵循业务流程：
    • 待激活 → 激活
    • 激活 → 挂失/注销
    • 挂失 → 激活（解挂）/注销
    • 注销后不可再变更状态
  3. 激活操作会自动记录激活时间
  4. 状态变更会记录操作日志

3. 通用说明

3.1 BaseEntity基础字段

所有实体对象继承自BaseEntity，包含以下通用字段：

字段名 类型 说明
createBy String 创建人
createTime Date 创建时间
updateBy String 更新人
updateTime Date 更新时间
remark String 备注

3.2 AjaxResult统一响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
字段名 类型 说明
code Integer 状态码
msg String 响应消息
data Object 响应数据

3.3 通用错误码

错误码 说明
200 成功
400 请求参数错误
401 未授权
403 禁止访问
404 资源不存在
500 服务器内部错误

3.4 请求头说明

所有接口建议携带以下请求头：

Header名称 说明 是否必填
Content-Type 请求内容类型 POST请求必填
Authorization 认证令牌（如需要） 视权限而定

3.5 接口调用地址

  • 开发环境: http://localhost:8080
  • 测试环境: http://test.example.com
  • 生产环境: http://api.example.com

完整URL示例:

开发环境：http://localhost:8080/batch/add
测试环境：http://test.example.com/batch/add
生产环境：http://api.example.com/batch/add

文档更新记录:

版本 日期 更新内容 更新人
v1.0 2024-11-12 初始版本 zf1017@foxmail.com

舒克