1. 获取卡密列表

接口地址： /merchantapi/goods/card/list

请求参数：

参数名	类型	必填	说明
goods_id	int	否	商品ID
status	int	否	卡密状态：-1=已删除，0=不可用，1=可用，2=已使用
number	string	否	卡号（模糊搜索）
trade_no	string	否	订单号（精确搜索）
cate_id	int	否	分类ID
page	int	否	页码（默认1）
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
          "id": 799, // 卡密ID
          "user_id": 1000, // 商户ID
          "goods_id": 1, // 商品ID
          "number": "499", // 卡号
          "secret": "Jy485TcdFbz8I2J", // 卡密
          "status": 1, // 状态 1:未售出 2:已售出
          "create_at": "2025-11-19 01:00:50", // 创建时间
          "delete_at": null, // 删除时间
          "sell_time": null, // 售出时间
          "is_first": 0, // 是否优先销售 0:否 1:是
          "unfreeze_at": 0, // 锁卡时间 预留字段 暂未使用
          "is_pre": 0, // 是否开启自定义前缀 0:否 1:是
          "pre_number": "", // 卡号前缀
          "pre_secret": "", // 卡密前缀
          "show_prefix": 1, // 是否显示前缀 0:不显示 1:显示
          "good_price": "15.00", // 商品价格
          "good_name": "1000的商品1", // 商品名称
          "category_name": "1000分类1", // 分类名称
      },
    ],
    "total": 1500 // 总数量
  }
}

---

2. 添加卡密

接口地址： /merchantapi/goods/card/add

请求参数：

参数名	类型	必填	说明
goods_id	int	是	商品ID
import_type	string	是	导入方式：1=文本导入，2=txt文件导入
split_type	string	是	分隔符：auto=自动识别，卡号+逗号+卡密，卡号+“
content	string	条件	卡密内容（文本导入时必填）
files	file	条件	卡密文件（文件导入时必填，最大20MB）
check_card	int	否	是否检查重复：0=不检查，1=检查（默认0）
is_first	int	否	是否优先销售：0=否，1=是（默认0）
show_prefix	int	否	是否显示前缀：0=不显示，1=显示（默认1）
is_pre	int	否	是否开启自定义前缀：0=否，1=是（默认0）
pre_number	string	条件	卡号前缀（is_pre=1时必填）
pre_secret	string	条件	卡密前缀（is_pre=1时必填）
order_type	int	否	插入方式：1=顺序插入，2=随机插入（默认1）

卡密内容格式：

卡号1 卡密1
卡号2 卡密2
卡号3 卡密3

或使用其他分隔符：

卡号1,卡密1
卡号2,卡密2
卡号3,卡密3

响应示例：

{
  "code": 1,
  "msg": "添加成功",
  "data": "成功添加1000张卡密！"
}

错误响应：

{
  "code": 0,
  "msg": "一次最多添加5000张，建议您分割后依次添加"
}

或

{
  "code": 0,
  "msg": "虚拟卡内容格式不正确, 或卡密已存在"
}

或

{
  "code": 0,
  "msg": "代理商品不能添加库存"
}

业务规则：

1. 一次最多添加5000张卡密
2. 文件导入时文件大小不能超过20MB
3. 支持自动识别分隔符（空格、逗号、竖线、----）
4. 可选择是否检查重复卡密
5. 可设置优先销售标记
6. 可设置卡号卡密前缀
7. 代理商品不能添加库存
8. 添加成功后会自动同步商品库存数量

---

3. 批量删除卡密

接口地址： /merchantapi/goods/card/del

请求参数：

参数名	类型	必填	说明
ids	array	是	卡密ID数组

请求示例：

{
  "ids": [1, 2, 3, 4, 5]
}

响应示例：

{
  "code": 1,
  "msg": "删除成功！"
}

说明： 删除操作为软删除，卡密会进入回收站，删除后会自动同步商品库存

---

4. 一键删除未售出库存

接口地址： /merchantapi/goods/card/allDel

请求参数： 无

响应示例：

{
  "code": 1,
  "msg": "删除成功！",
  "data": {
    "taskId": "clear_cards_abc123"
  }
}

说明：

• 该操作会删除所有未售出的卡密（status=0或1）
• 删除操作为后台异步任务，返回任务ID
• 可通过任务ID查询删除进度
• 删除后会将所有商品库存设置为0

---

5. 获取删除进度

接口地址： /merchantapi/goods/card/getAllDelProgress

请求参数：

参数名	类型	必填	说明
taskId	string	是	任务ID

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "progress": 75.50,
    "status": "processing",
    "deleted": 7550,
    "total": 10000
  }
}

字段说明：

• progress: 删除进度（百分比）
• status: 任务状态：processing=处理中，completed=已完成
• deleted: 已删除数量
• total: 总数量

---

6. 卡密回收站列表

接口地址： /merchantapi/goods/card/trash

请求参数：

参数名	类型	必填	说明
goods_id	int	否	商品ID
status	int	否	卡密状态
cate_id	int	否	分类ID
page	int	否	页码（默认1）
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
       {
          "id": 800,
          "user_id": 1000,
          "goods_id": 1,
          "number": "500",
          "secret": "LJc56UtfsyX943P",
          "status": 1,
          "create_at": "2025-11-19 01:00:50",
          "delete_at": "2025-11-22 21:47:16",
          "sell_time": null,
          "is_first": 0,
          "unfreeze_at": 0,
          "is_pre": 0,
          "pre_number": "",
          "pre_secret": "",
          "show_prefix": 1,
          "goods_name": "1000的商品1",
          "cate_name": "1000分类1",
          "price": "15.00"
      },
    ],
    "total": 50
  }
}

---

7. 回收站批量删除

接口地址： /merchantapi/goods/card/trashBatchDel

请求参数：

参数名	类型	必填	说明
ids	array	是	卡密ID数组

请求示例：

{
  "ids": [1, 2, 3]
}

响应示例：

{
  "code": 1,
  "msg": "删除成功！"
}

说明： 该操作为物理删除，删除后无法恢复

---

8. 清空回收站

接口地址： /merchantapi/goods/card/clear

请求参数： 无

响应示例：

{
  "code": 1,
  "msg": "删除成功！",
  "data": {
    "taskId": "clear_cards_xyz789"
  }
}

说明：

• 该操作会清空回收站中的所有卡密
• 删除操作为异步任务，返回任务ID
• 可通过任务ID查询删除进度
• 该操作为物理删除，删除后无法恢复

---

9. 回收站批量恢复

接口地址： /merchantapi/goods/card/trashBatchRestore

请求参数：

参数名	类型	必填	说明
ids	array	是	卡密ID数组

请求示例：

{
  "ids": [1, 2, 3]
}

响应示例：

{
  "code": 1,
  "msg": "恢复成功！"
}

说明： 恢复后卡密会重新进入可用库存

---

10. 导出卡密

接口地址： /merchantapi/goods/card/dumpCards

请求参数：

参数名	类型	必填	说明
goods_id	int	是	商品ID
status	string	否	卡密状态（逗号分隔，1=未售出，2=已售出）
range	int	否	导出范围：0=全部，1=指定数量（默认0）
number	int	条件	导出数量（range=1时必填，不填则导出全部）
del	int	否	导出后是否删除：0=否，1=是（默认0）
need_goods_name	int	否	是否包含商品名称：0=否，1=是（默认0）
file_type	int	否	文件类型：0=Excel，1=TXT（默认0）

响应示例：

{
  "code": 1,
  "msg": "导出成功",
  "data": {
    "url": "https://fast.qqss.net/home/download/export?key=5822bfcb33a5d1de1928bf86a19ee3fe1763819388",
  }
}

错误响应：

{
  "code": 0,
  "msg": "库存数量超过2W，请分批导出 或者 导出TXT格式"
}

业务规则：

1. Excel格式导出时，库存数量不能超过2万张
2. TXT格式无数量限制
3. 可选择导出后是否删除卡密
4. 可选择是否在导出文件中包含商品名称
5. 导出文件名格式：商品名称的虚拟卡_日期.扩展名

导出文件格式（Excel）：

序号	商品名称（可选）	卡号	卡密
1	QQ币100元	1234567890	abcdefghij
2	QQ币100元	0987654321	jihgfedcba

导出文件格式（TXT）：

序号	商品名称（可选）	卡号	卡密
1	QQ币100元	1234567890	abcdefghij
2	QQ币100元	0987654321	jihgfedcba

---

11. 设置优先销售

接口地址： /merchantapi/goods/card/first

请求参数：

参数名	类型	必填	说明
id	int	是	卡密ID
status	int	是	优先销售状态：0=否，1=是

响应示例：

{
  "code": 1,
  "msg": "设置成功！"
}

说明： 设置为优先销售的卡密会在发货时优先被选中

---

业务规则

1. 导入规则

• 一次最多导入5000张卡密
• 文件导入时文件大小不能超过20MB
• 支持多种分隔符：空格、逗号、竖线、----
• 可自动识别分隔符类型
• 支持检查重复卡密
• 代理商品不能添加库存

2. 删除规则

• 普通删除为软删除，卡密进入回收站
• 回收站删除为物理删除，无法恢复
• 删除后会自动同步商品库存数量
• 一键删除未售出库存为异步操作

3. 导出规则

• Excel格式最多导出2万张
• TXT格式无数量限制
• 可选择导出后是否删除
• 导出文件名包含商品名称和日期

4. 发卡规则

• 优先销售的卡密会优先发货
• 商品设置的发卡顺序影响发货顺序
• 卡密前缀在发货时会自动添加包含格式化后卡密信息\以及原始行

注意事项

• 代理商品不能添加库存，只能由源头商户添加
• 删除卡密会自动同步商品库存数量
• 大批量操作（一键删除、清空回收站）为异步任务
• 导出大量卡密时建议使用TXT格式
• 卡密前缀功能可用于批量管理不同批次的卡密
• 优先销售功能可用于优先消耗特定批次的卡密
• 回收站中的卡密可以恢复，但物理删除后无法恢复