点卡系统

点卡系统 API 文档

本文档描述【点卡系统】提供的所有 API 接口。点卡系统是可进行点卡创建、销毁、扣点、余额查询等操作的积分记账系统，可方便地进行各种扣点系统创建。

接口列表

1. 批量创建点卡

端点：/pointcard/batchCreate
请求方法：GET / POST
功能：批量生成有限数量的点卡，每张卡具有指定初始余额，并自动激活。

请求参数

参数名 类型 必填 默认值 说明
count number 否 1 创建的点卡数量
balance number 否 100 每张卡的初始可用点数

注意：需要提供 secret_key 参数进行鉴权（参照全局 pointcard_key_filter）。

返回结果

{
  "ret": true,
  "msg": "success",
  "cards": [
    {
      "cardId": "32位十六进制大写字符串",
      "balance": 100,
      "isActive": true,
      "createdAt": 1712345678901
    }
  ]
}

返回字段说明

字段 类型 说明
ret boolean 操作是否成功
msg string 描述信息
cards array 成功创建的点卡对象列表
cards[].cardId string 32位点卡唯一标识
cards[].balance number 点卡初始余额
cards[].isActive boolean 是否激活（始终为 true）
cards[].createdAt number 创建时间戳（毫秒）

失败情况

  • { "ret": false, "msg": "closed" } —— 系统已关闭
  • { "ret": false, "msg": "secret_key error!" } —— 密钥错误
  • { "ret": false, "msg": "create card failed", "cardId": "xxx" } —— 单卡创建失败
  • { "ret": false, "msg": "update card list failed" } —— 更新点卡列表失败

2. 批量取消点卡

端点：/pointcard/batchCancel
请求方法：GET / POST
功能：批量将指定点卡标记为未激活（不可用）。

请求参数

参数名 类型 必填 说明
cardIds string 是 JSON 数组字符串，如 ["CARD1","CARD2"]，表示要取消的点卡 ID 列表

密钥鉴权同 batchCreate。

返回结果

{
  "ret": true,
  "msg": "batch cancel completed",
  "results": [
    {
      "cardId": "CARD1",
      "ret": true,
      "msg": "success"
    },
    {
      "cardId": "CARD2",
      "ret": false,
      "msg": "card not found"
    }
  ]
}

返回字段说明

字段 类型 说明
ret boolean 批量操作整体是否成功（仅当解析 cardIds 异常时可能为 true 但 msg 异常）
msg string 描述信息
results array 每张卡的处理结果列表
results[].cardId string 点卡 ID
results[].ret boolean 该卡操作是否成功
results[].msg string 成功："success"，失败：错误原因

3. 查询点卡状态

端点：/pointcard/status
请求方法：GET / POST
功能：获取单张点卡的完整信息，包括余额、激活状态等。

请求参数

参数名 类型 必填 说明
cardId string 是 点卡 ID

需要有效用户 session。

返回结果

{
  "cardId": "CARD_ID",
  "balance": 100,
  "isActive": true,
  "createdAt": 1712345678901,
  "ret": true,
  "msg": "success"
}

返回字段说明

字段 类型 说明
cardId string 点卡 ID
balance number 当前剩余点数
isActive boolean 是否激活
createdAt number 创建时间戳
ret boolean 是否成功
msg string 描述信息

失败情况

  • { "ret": false, "msg": "card not found" }

4. 扣减点数

端点：/pointcard/deduct
请求方法：GET / POST
功能：从指定点卡中扣除相应点数，要求卡处于激活状态且余额充足。

请求参数

参数名 类型 必填 默认值 说明
cardId string 是 — 点卡 ID
points number 否 0 要扣除的点数

需要有效用户 session。

返回结果

{
  "ret": true,
  "msg": "success",
  "newBalance": 50
}

返回字段说明

字段 类型 说明
ret boolean 是否成功
msg string 描述信息
newBalance number 扣减后的新余额

失败情况

  • { "ret": false, "msg": "card not found" }
  • { "ret": false, "msg": "card is inactive" }
  • { "ret": false, "msg": "insufficient balance" }
  • { "ret": false, "msg": "deduct failed" }

5. 查询点卡余额

端点：/pointcard/balance
请求方法：GET / POST
功能：查询指定点卡的余额和激活状态，不返回其他冗余字段。

请求参数

参数名 类型 必填 说明
cardId string 是 点卡 ID

需要有效用户 session。

返回结果

{
  "ret": true,
  "msg": "success",
  "balance": 100,
  "isActive": true
}

返回字段说明

字段 类型 说明
ret boolean 是否成功
msg string 描述信息
balance number 当前余额
isActive boolean 是否激活

失败情况

  • { "ret": false, "msg": "card not found" }

6. 调用点卡应用（扣费并调用第三方 API）

端点：/pointcard/call
请求方法：GET / POST
功能：根据配置的应用名称，先扣除指定点数，再调用对应应用的 API 处理请求。需在配置文件 rtpointcard-setting.json 中定义 card_apps。

请求参数

参数名 类型 必填 说明
cardId string 是 点卡 ID
card_app_name string 是 应用名称，需匹配配置中的 app_name
... any 否 其余参数透传给目标应用 API

需要有效用户 session。

返回结果

  • 扣费成功且目标 API 正常返回时，结果由目标 API 决定（透传）。
  • 扣费失败时返回：
{
  "ret": false,
  "msg": "deduct card points failed"
}
  • 应用未配置或 API 不存在时返回：
{
  "ret": false,
  "msg": "card app is empty"
}

7. 分页查询点卡列表（新增）

端点：/pointcard/list
请求方法：GET / POST
功能：分页获取所有已创建的点卡的详细信息，包含总数、总页数等。

请求参数

参数名 类型 必填 默认值 说明
page number 否 1 当前页码
pageSize number 否 10 每页条数（最大建议100）

需要有效用户 session。

返回结果

{
  "ret": true,
  "msg": "success",
  "data": {
    "total": 100,
    "totalPages": 10,
    "currentPage": 1,
    "pageSize": 10,
    "cards": [
      {
        "cardId": "CARD_ID",
        "balance": 100,
        "isActive": true,
        "createdAt": 1712345678901
      }
    ]
  }
}

返回字段说明

字段 类型 说明
ret boolean 是否成功
msg string 描述信息
data object 分页数据
data.total number 点卡总数
data.totalPages number 总页数
data.currentPage number 当前页码
data.pageSize number 每页条数
data.cards array 当前页的点卡对象列表
data.cards[].cardId string 点卡 ID
data.cards[].balance number 当前余额
data.cards[].isActive boolean 是否激活
data.cards[].createdAt number 创建时间戳

失败情况

  • { "ret": false, "msg": "get card list failed: ..." }

公共鉴权说明

  • 对于 /pointcard/batchCreate 和 /pointcard/batchCancel，需在请求中提供 secret_key 参数，与配置文件 rtpointcard-setting.json 中的 secret_key 比对，若不匹配则返回密钥错误。
  • 对于 /pointcard/status, /pointcard/deduct, /pointcard/balance, /pointcard/call, /pointcard/list，需提供有效的用户 session（由 session_filter 中间件验证）。
  • 当配置文件中的 closed 字段为 true 时，所有接口均返回 { "ret": false, "msg": "closed" }。

数据结构说明

点卡对象（Card Object）

字段 类型 说明
cardId string 32位唯一标识（十六进制大写）
balance number 当前可用点数
isActive boolean 是否激活（可被消费）
createdAt number 创建时的时间戳（毫秒）

存储方式：

  • 每张卡以键 pointcard:${cardId} 存储在数据库中，值为上述对象的 JSON 字符串。
  • 全局点卡 ID 列表以键 pointcard:list 存储为一个 JSON 数组字符串（包含所有卡 ID）。