预付卡接口文档

查询预付卡消费明细

POST

按 ID 游标分页查询预付卡消费明细，可按消费时间、预付卡 UID、预付卡卡号或操作类型过滤，固定返回预付卡卡号和销售单号。

连锁规则：传总部 account 时， 查所有门店消费明细；传子门店 account 时，只查该子门店的消费明细。

请求参数

参数	类型	必填	说明
account	string	是	查询范围账号。总部账号查全部，子门店只查本店消费明细。
datetimeBegin	string	否	消费开始时间，格式 yyyy-MM-dd HH:mm:ss，包含该时间。按时间过滤时需与 datetimeEnd 成对传入。
datetimeEnd	string	否	消费结束时间，不包含该时间。按时间过滤时需与 datetimeBegin 成对传入，且必须大于 datetimeBegin。
cardUid	long	否	按预付卡 UID 精确查询。
cardNumber	string	否	按预付卡卡号精确查询。
operateType	int	否	操作类型。1:销售;2:退货;3:销售单据反结账;4:退货单据反结账;10:网单使用预付卡支付
lastId	long	否	翻页游标。首次传 0 或不传；后续传上次响应的 nextLastId。
order	string	否	排序方向，支持 desc、asc，默认 desc。
limit	int	否	分页大小，默认 100，最大 100。

请求示例

{
  "account": "store001",
  "datetimeBegin": "2026-07-26 15:02:47",
  "datetimeEnd": "2026-07-29 15:02:47",
  "cardUid": 123456,
  "cardNumber": "10000001",
  "operateType": 1,
  "lastId": 0,
  "order": "desc",
  "limit": 100
}

返回字段

字段	类型	说明
list	array	预付卡消费明细列表。
list[].id	long	消费明细记录 ID。
list[].userId	int	消费门店 userId。
list[].cardUserId	int	预付卡归属总部或单店 userId。
list[].cardUid	long	预付卡 UID。
list[].cardNumber	string	预付卡卡号。
list[].ticketUid	long	销售单据 UID。
list[].ticketSn	string	销售单号。
list[].usedBalance	decimal	使用金额。
list[].refundBalance	decimal	已退金额。
list[].datetime	string	消费时间，格式 yyyy-MM-dd HH:mm:ss。
list[].operateType	int	操作类型。1:销售;2:退货;3:销售单据反结账;4:退货单据反结账;10:网单使用预付卡支付
list[].afterUsedBalance	decimal	操作后余额。
list[].useGiftBalance	decimal	使用赠送金额，属于 usedBalance 的一部分。
list[].productOrderNo	string	网单号。
hasMore	boolean	是否还有下一页。
nextLastId	long	下一页游标。继续翻页时传入请求参数 lastId。

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "825",
        "userId": 5918635,
        "cardUserId": 5918635,
        "cardUid": "123456",
        "cardNumber": "10000001",
        "ticketUid": "987654",
        "ticketSn": "XS202607290001",
        "usedBalance": 10.00,
        "refundBalance": 0.00,
        "datetime": "2026-07-29 15:02:47",
        "operateType": 1,
        "afterUsedBalance": 90.00,
        "useGiftBalance": 2.00,
        "productOrderNo": "PO202607290001"
      }
    ],
    "hasMore": false,
    "nextLastId": "825"
  }
}

查询预付卡详情

POST

按卡号、制卡时间或激活时间分页查询预付卡详情；不传过滤条件时按 id 游标分页返回。

金额规则：reciveAmount 为实收，cardBalance 为面值。

请求参数

参数	类型	必填	说明
account	string	是	查询范围账号。总部账号查全部，子门店只查本店归属卡。
cardNumberList	array<string>	否	预付卡卡号列表，最多 100 个。有效卡号只有 1 个时按精确查询计费。
createDateTimeBegin	string	否	制卡开始时间，格式 yyyy-MM-dd HH:mm:ss，与 createDateTimeEnd 成对传入。
createDateTimeEnd	string	否	制卡结束时间，不包含该时间，必须大于开始时间，跨度不能超过 90 天。
activateDateTimeBegin	string	否	激活开始时间，格式 yyyy-MM-dd HH:mm:ss，与 activateDateTimeEnd 成对传入。
activateDateTimeEnd	string	否	激活结束时间，不包含该时间，必须大于开始时间，跨度不能超过 90 天。
lastId	long	否	翻页游标。首次传 0 或不传；后续传上次响应的 nextLastId。
order	string	否	排序方向，支持 desc、asc，默认 desc。
limit	int	否	分页大小，默认 100，最大 100。

不传 cardNumberList、制卡时间范围和激活时间范围时，按 id 游标分页返回当前账号范围内的预付卡明细，并按普通查询计费 500 token/次。

请求示例

{
  "account": "store001",
  "lastId": 0,
  "order": "asc",
  "limit": 100
}

返回字段

字段	类型	说明
list	array	预付卡列表。
list[].id	long	预付卡记录 ID，也是翻页游标。
list[].userId	int	预付卡归属总部或单店 userId。
list[].uid	long	预付卡 UID。
list[].cardNumber	string	预付卡卡号。
list[].balance	decimal	当前余额。
list[].enable	int	是否激活，通常 1 表示已激活。
list[].status	int	卡状态，0 或空表示正常，1 表示禁用。
list[].belongUserId	int	归属门店 userId。该字段由系统按查询账号权限返回，外部请求不传。
list[].createDateTime	string	制卡时间，格式 yyyy-MM-dd HH:mm:ss。
list[].activateDateTime	string	激活时间，格式 yyyy-MM-dd HH:mm:ss。
list[].ruleName	string	预付卡规则名称。
list[].reciveAmount	decimal	实收金额。例如花 90 元买 100 元面值卡时，该字段为 90。
list[].cardBalance	decimal	卡面值。例如花 90 元买 100 元面值卡时，该字段为 100。
hasMore	boolean	是否还有下一页。
nextLastId	long	下一页游标。继续翻页时传入请求参数 lastId。

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "548416",
        "userId": 5918635,
        "uid": "123456",
        "cardNumber": "10000001",
        "balance": 90.00,
        "enable": 1,
        "status": 0,
        "belongUserId": 5918635,
        "createDateTime": "2026-07-01 10:00:00",
        "activateDateTime": "2026-07-02 10:00:00",
        "ruleName": "100元预付卡",
        "reciveAmount": 90.00,
        "cardBalance": 100.00
      }
    ],
    "hasMore": false,
    "nextLastId": "548416"
  }
}