# Apple Card API

<cite>
**Referenced Files in This Document**   
- [apple-card-info.ts](file://src/api/apple-card-info.ts)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [kami-api-card-info-apple-v1-card-info-create-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-create-req.ts)
- [kami-api-card-info-apple-v1-card-info-update-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-update-req.ts)
- [kami-api-card-info-apple-v1-card-info-delete-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-delete-req.ts)
- [kami-api-card-info-apple-v1-card-info-batch-add-from-xlsx-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-batch-add-from-xlsx-req.ts)
- [kami-api-card-info-apple-v1-card-history-info-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-history-info-list-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts)
- [kami-api-card-info-apple-v1-recharge-history-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-req.ts)
- [kami-api-card-info-apple-v1-card-info-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-list-req.ts)
- [kami-api-card-info-apple-v1-card-info-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-list-res.ts)
- [kami-api-card-info-apple-v1-card-history-info-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-history-info-list-res.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-list-res.ts)
- [kami-api-card-info-apple-v1-recharge-history-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-res.ts)
- [kami-api-card-info-apple-v1-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-config-set-req.ts)
- [kami-api-card-info-apple-v1-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-config-get-res.ts)
- [kami-api-card-info-apple-v1-recharge-steal-setting-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-setting-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-setting-get-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-setting-get-res.ts)
</cite>

## Table of Contents

1. [Apple Card信息管理API](#apple-card信息管理api)
2. [充值历史查询API](#充值历史查询api)
3. [抽卡设置API](#抽卡设置api)
4. [错误处理与常见问题](#错误处理与常见问题)

## Apple Card信息管理API

Apple Card信息管理API提供了一套完整的卡券生命周期管理功能，包括卡券的创建、更新、删除和批量导入等操作。这些API接口位于`src/api/apple-card-info.ts`文件中，通过HTTP请求与后端服务进行交互。

### 卡券信息创建接口

卡券信息创建接口用于向系统中添加新的Apple Card账户。该接口接收包含账户信息、密码、充值限额等参数的请求体。

**接口功能**:

- 创建新的Apple Card账户
- 设置账户的最大充值金额和次数限制
- 添加账户备注信息

**请求参数**:

- `account`: 账户名
- `password`: 密码
- `maxAmountLimit`: 最大充值金额
- `maxCountLimit`: 最大充值次数
- `remark`: 备注（可选）

**Section sources**

- [kami-api-card-info-apple-v1-card-info-create-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-create-req.ts#L19-L50)
- [apple-card-info.ts](file://src/api/apple-card-info.ts#L60-L63)

### 卡券信息更新接口

卡券信息更新接口用于修改现有Apple Card账户的信息。该接口需要提供账户的唯一标识符以及需要更新的字段。

**接口功能**:

- 更新Apple Card账户的基本信息
- 修改充值限额设置
- 更新账户备注

**请求参数**:

- `id`: 账户唯一标识符
- `account`: 账户名
- `password`: 密码
- `maxAmountLimit`: 最大充值金额
- `maxCountLimit`: 最大充值次数
- `remark`: 备注（可选）

**Section sources**

- [kami-api-card-info-apple-v1-card-info-update-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-update-req.ts#L19-L56)
- [apple-card-info.ts](file://src/api/apple-card-info.ts#L65-L68)

### 卡券信息删除接口

卡券信息删除接口用于从系统中移除指定的Apple Card账户。该操作是不可逆的，删除后账户信息将无法恢复。

**接口功能**:

- 根据ID删除指定的Apple Card账户
- 执行软删除操作，保留删除记录

**请求参数**:

- `id`: 需要删除的账户唯一标识符

**Section sources**

- [kami-api-card-info-apple-v1-card-info-delete-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-delete-req.ts#L19-L26)
- [apple-card-info.ts](file://src/api/apple-card-info.ts#L70-L73)

### 卡券信息批量导入接口

卡券信息批量导入接口支持通过上传Excel文件的方式批量添加多个Apple Card账户，极大地提高了大规模账户管理的效率。

**接口功能**:

- 支持批量导入Apple Card账户信息
- 通过文件上传方式处理大量数据
- 提供模板下载功能以确保数据格式正确

**请求参数**:

- `file`: 包含账户信息的Excel文件

**Section sources**

- [kami-api-card-info-apple-v1-card-info-batch-add-from-xlsx-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-batch-add-from-xlsx-req.ts#L19-L26)
- [apple-card-info.ts](file://src/api/apple-card-info.ts#L75-L84)

### 卡券信息查询接口

卡券信息查询接口提供了分页查询Apple Card账户列表的功能，支持根据账户名等条件进行筛选。

**接口功能**:

- 分页获取Apple Card账户列表
- 支持按账户名进行搜索
- 返回账户状态、余额等详细信息

**请求参数**:

- `account`: 账户名（可选）
- `current`: 当前页码
- `pageSize`: 每页显示数量

**响应结构**:

- `total`: 总记录数
- `list`: 账户信息列表，包含账户状态、今日充值金额、余额等信息

**Section sources**

- [kami-api-card-info-apple-v1-card-info-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-list-req.ts#L19-L38)
- [kami-api-card-info-apple-v1-card-info-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-card-info-list-res.ts#L23-L36)
- [apple-card-info.ts](file://src/api/apple-card-info.ts#L40-L58)

## 充值历史查询API

充值历史查询API提供了对Apple Card充值记录的全面查询功能，包括充值订单列表、操作历史记录以及相关数据导出等操作。

### 充值历史列表查询接口

充值历史列表查询接口用于获取系统的充值订单记录，支持多种过滤条件和分页处理。

**接口功能**:

- 分页查询充值订单列表
- 支持按订单号、日期范围等条件过滤
- 获取订单的实际充值金额、卡面额、余额等信息

**请求参数**:

- `orderNo`: 订单ID
- `dateRange`: 日期范围
- `current`: 当前页码
- `pageSize`: 每页显示数量

**响应结构**:

- `list`: 充值订单列表，包含订单号、实际金额、卡面额、账户余额、创建时间等信息

**Section sources**

- [kami-api-card-info-apple-v1-recharge-history-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-req.ts#L19-L26)
- [kami-api-card-info-apple-v1-recharge-history-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-res.ts#L23-L30)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L40-L68)

### 充值操作历史查询接口

充值操作历史查询接口用于获取特定充值订单的详细操作记录，帮助追踪订单的处理过程。

**接口功能**:

- 查询指定订单的操作历史
- 获取每次操作的类型、备注和时间
- 追踪订单状态变更过程

**请求参数**:

- `orderNo`: 订单号

**响应结构**:

- `id`: 操作记录ID
- `rechargeId`: 充值ID
- `account`: 操作账户
- `operation`: 操作类型
- `remark`: 操作备注
- `createdAt`: 操作时间

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L70-L78)

### 充值历史数据导出接口

充值历史数据导出接口支持将查询到的充值记录导出为Excel文件，便于离线分析和存档。

**接口功能**:

- 将充值记录导出为Excel文件
- 支持按订单号筛选导出数据
- 提供文件下载功能

**请求参数**:

- `orderNo`: 订单号

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L108-L118)

### 充值订单管理接口

充值订单管理接口提供了一系列对充值订单的管理功能，包括手动回调、金额修改、状态重置等操作。

**主要功能**:

- **手动回调订单**: 当自动回调失败时，支持手动触发回调
- **修改实际金额**: 更正订单的实际充值金额
- **重置订单状态**: 将订单状态重置为初始状态，便于重新处理

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L80-L106)

## 抽卡设置API

抽卡设置API用于管理Apple Card的抽卡规则和全局设置，包括抽卡规则的增删改查以及全局开关控制。

### 抽卡规则管理接口

抽卡规则管理接口提供了一套完整的抽卡规则生命周期管理功能。

#### 添加抽卡规则

**接口功能**:

- 创建新的抽卡规则
- 设置规则名称、目标用户、存储用户等参数

**请求参数**:

- `name`: 规则名称
- `targetUserId`: 目标用户ID
- `storageUserId`: 存储用户ID
- `amount`: 金额
- `targetAmount`: 目标金额
- `intervalTime`: 时间间隔
- `status`: 规则状态

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts#L19-L62)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L58-L61)

#### 编辑抽卡规则

**接口功能**:

- 更新现有抽卡规则的配置
- 修改规则的各种参数

**请求参数**:

- `id`: 规则ID
- `name`: 规则名称
- `targetUserId`: 目标用户ID
- `storageUserId`: 存储用户ID
- `amount`: 金额
- `targetAmount`: 目标金额
- `intervalTime`: 时间间隔
- `status`: 规则状态

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts#L19-L68)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L63-L66)

#### 删除抽卡规则

**接口功能**:

- 删除指定的抽卡规则
- 根据规则ID执行删除操作

**请求参数**:

- `id`: 需要删除的规则ID

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts#L19-L26)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L68-L71)

#### 查询抽卡规则列表

**接口功能**:

- 分页查询抽卡规则列表
- 获取规则的创建时间、更新时间等信息

**请求参数**:

- `current`: 当前页码
- `pageSize`: 每页显示数量

**响应结构**:

- `total`: 总记录数
- `list`: 规则列表，包含规则ID、名称、目标用户、存储用户、金额、目标金额、时间间隔、状态、总抽卡金额、创建时间和更新时间

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts#L19-L32)
- [kami-api-card-info-apple-v1-recharge-steal-rule-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-list-res.ts#L23-L36)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L40-L48)

### 抽卡全局设置接口

抽卡全局设置接口用于控制整个系统的抽卡功能开关和单个规则的状态。

#### 设置抽卡全局状态

**接口功能**:

- 开启或关闭系统的抽卡功能
- 控制抽卡功能的整体启用状态

**请求参数**:

- `stealStatus`: 抽卡状态（0: 关闭, 1: 开启）

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-setting-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-setting-req.ts#L19-L26)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L10-L13)

#### 获取抽卡全局状态

**接口功能**:

- 查询当前系统的抽卡功能状态
- 返回抽卡功能是否启用

**响应结构**:

- `stealStatus`: 抽卡状态（0: 关闭, 1: 开启）

**Section sources**

- [kami-api-card-info-apple-v1-recharge-steal-setting-get-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-setting-get-res.ts#L19-L26)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L15-L18)

#### 设置单个抽卡规则状态

**接口功能**:

- 启用或禁用特定的抽卡规则
- 对单个规则进行状态控制

**请求参数**:

- `id`: 规则ID
- `status`: 规则状态（0: 禁用, 1: 启用）

**Section sources**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L20-L23)

## 错误处理与常见问题

### 错误处理建议

在调用Apple Card API时，应实施适当的错误处理机制：

1. **网络错误处理**: 捕获网络连接异常，实现重试机制
2. **HTTP状态码处理**: 根据不同的HTTP状态码采取相应的处理策略
3. **数据验证**: 在发送请求前验证数据的完整性和正确性
4. **超时处理**: 设置合理的请求超时时间，避免长时间等待

### 常见问题解决方案

#### 批量导入失败

**问题**: Excel文件导入时出现格式错误
**解决方案**:

- 下载并使用系统提供的模板
- 确保文件编码为UTF-8
- 检查必填字段是否完整

#### 充值回调失败

**问题**: 充值成功后未收到回调通知
**解决方案**:

- 检查回调URL配置是否正确
- 验证服务器是否能够正常接收外部请求
- 使用手动回调接口进行补救

#### 抽卡规则不生效

**问题**: 设置的抽卡规则未按预期执行
**解决方案**:

- 确认抽卡功能全局开关已开启
- 检查规则状态是否为启用状态
- 验证目标用户和存储用户的配置是否正确

**Section sources**

- [apple-card-info.ts](file://src/api/apple-card-info.ts)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
