Youzan Valuecard

---
name: youzan-valuecard
version: 1.1.37
description: "储值卡模板、持卡详情和储值交易流水的原始数据查询与导出；不提供储值卡余额、有效期、充值或调账的远端数据变更能力，不做趋势、画像或推荐。"
---

# 储值卡

使用本 skill 前，确认当前授权范围、店铺上下文和金额单位。涉及客户权益卡实例时使用 `youzan-member`，金额和余额字段按接口返回单位解析。

## 查询数量限制

- 列表查询必须显式传入页码和每页数量，不得依赖接口默认分页；每页最多查询 20 条。
- 批量查询每批最多传入 20 个对象或标识；超过 20 个时必须拆分为多个批次依次查询，且每批均不得超过 20 个。

## 支持能力

- 查询储值卡和礼品卡模板、规则、面额及充值设置。
- 查询储值卡列表和单张储值卡详情，读取卡状态、余额、客户关联和有效期。
- 查询储值交易流水，包括充值、消费、退款、调账和激活等类型。
- 批量导出储值交易原始记录，并查看导出任务结果。
- 区分储值卡、礼品卡和提货卡，避免将卡类型或卡号混用。

## 字段提示

- 查询参数和返回结果中的字段必须使用中文字段名，不展示接口英文原始字段名。

### 必填信息

- 查询单张储值卡详情时必须提供卡号；按客户查询时必须提供客户手机号。
- 查询指定模板详情时必须提供模板标识。
- 按时间查询交易流水时必须同时提供开始时间和结束时间。
- 按客户或卡号筛选交易时必须提供客户手机号或卡号。

### 非必填信息

- 卡片列表的卡类型、状态、客户、有效期、余额范围和关键词条件可选；分页参数必须按“查询数量限制”传入。
- 交易流水列表的交易类型、卡类型、客户、卡号和门店条件可选；分页参数必须按“查询数量限制”传入。
- 批量导出可补充输出格式、字段范围和时间范围。

## 使用案例

- 用户说“查某张储值卡余额和有效期”时，必须提供卡号或卡片标识，并按返回字段说明余额单位。
- 用户说“查某客户近 30 天的储值交易”时，补齐客户手机号、开始时间和结束时间；不要把客户姓名当作客户定位条件。
- 用户说“导出某时间段的储值交易”时，明确时间范围、字段范围和输出格式，并说明导出结果是原始记录。
- 用户说“充值、调账、激活或作废储值卡”时，说明本 skill 只支持读取和导出。

## 边界

- 储值卡充值、余额调账、有效期调整、激活、作废和其他远端数据变更不在本入口范围内。
- 权益卡模板和客户权益卡实例使用 `youzan-member`。
- 不从余额或交易流水直接推导留存、复购、资金趋势或经营结论。