# 沃尔玛账户管理API

<cite>
**本文档中引用的文件**  
- [kami-api-card-info-walmart-v1-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-create-req.ts)
- [kami-api-card-info-walmart-v1-account-status-detect-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-req.ts)
- [kami-api-card-info-walmart-v1-account-status-detect-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-res.ts)
- [kami-api-card-info-walmart-v1-group-list-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-group-list-req.ts)
- [kami-api-card-info-walmart-v1-v1-card-redeem-account-group-entity.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-v1-card-redeem-account-group-entity.ts)
- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
</cite>

## 目录

1. [介绍](#介绍)
2. [核心功能概览](#核心功能概览)
3. [账户创建API](#账户创建api)
4. [账户状态检测API](#账户状态检测api)
5. [每日摘要查询API](#每日摘要查询api)
6. [账户组管理API](#账户组管理api)
7. [分页与数据过滤](#分页与数据过滤)
8. [错误处理策略](#错误处理策略)
9. [常见问题排查](#常见问题排查)
10. [附录](#附录)

## 介绍

本文档详细介绍了沃尔玛账户管理API的核心功能和使用方法。该API系统支持账户的全生命周期管理，包括账户创建、状态检测、每日摘要查询以及账户组的增删改查和统计分析功能。文档涵盖了主要请求模型的字段含义、API调用示例、分页机制、数据过滤参数和错误处理策略，为开发者提供全面的技术指导。

## 核心功能概览

沃尔玛账户管理API提供了完整的账户管理解决方案，主要功能包括：

- 账户创建与配置
- 账户状态实时检测
- 每日交易摘要查询
- 账户组的管理与统计分析
- 账户列表查询与数据导出

这些功能通过清晰的RESTful接口提供，支持灵活的参数过滤和分页机制，满足不同场景下的使用需求。

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

## 账户创建API

账户创建API用于在系统中注册新的沃尔玛账户，通过`KamiApiCardInfoWalmartV1AccountCreateReq`请求模型传递必要的账户信息。

### 请求模型字段说明

`KamiApiCardInfoWalmartV1AccountCreateReq`模型包含以下关键字段：

| 字段名         | 类型   | 是否必填 | 描述                     |
| -------------- | ------ | -------- | ------------------------ |
| cookie         | string | 是       | 账户认证cookie，不能为空 |
| name           | string | 否       | 账户别名                 |
| groupId        | number | 否       | 所属分组ID               |
| maxAmountLimit | number | 是       | 最大充值限制金额         |
| maxCountLimit  | number | 是       | 最大充值次数限制         |
| status         | number | 否       | 账户状态                 |
| remark         | string | 否       | 备注信息                 |

**Section sources**

- [kami-api-card-info-walmart-v1-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-create-req.ts)

## 账户状态检测API

账户状态检测API用于检查指定账户的当前状态，确保账户的可用性。

### 请求与响应模型

- **请求模型**: `KamiApiCardInfoWalmartV1AccountStatusDetectReq`

  - 包含`id`字段，用于指定要检测的账户ID

- **响应模型**: `KamiApiCardInfoWalmartV1AccountStatusDetectRes`
  - 包含`status`字段，布尔类型，表示账户是否有效

### API调用流程

```mermaid
sequenceDiagram
participant 客户端
participant API
participant 服务端
客户端->>API : 发送状态检测请求(id)
API->>服务端 : 转发请求并验证账户
服务端-->>API : 返回状态结果
API-->>客户端 : 返回{status : boolean}
```

**Diagram sources**

- [kami-api-card-info-walmart-v1-account-status-detect-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-req.ts)
- [kami-api-card-info-walmart-v1-account-status-detect-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-res.ts)
- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

**Section sources**

- [kami-api-card-info-walmart-v1-account-status-detect-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-req.ts)
- [kami-api-card-info-walmart-v1-account-status-detect-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-res.ts)

## 每日摘要查询API

每日摘要查询API用于获取指定日期的账户交易汇总信息，支持按账户、分组等条件进行过滤。

### 查询参数

- 日期范围过滤
- 账户名称过滤
- 分组ID过滤
- 用户ID过滤

该API支持将查询结果导出为Excel格式，便于后续分析和报表生成。

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

## 账户组管理API

账户组管理API提供了对账户分组的完整CRUD操作和统计分析功能。

### 核心功能

- **组的增删改查**: 支持创建、删除、更新和查询账户分组
- **统计分析**: 提供分组级别的交易统计和账户数量统计
- **批量操作**: 支持对组内所有账户进行批量状态刷新等操作

### 统计数据模型

`KamiApiCardInfoWalmartV1V1CardRedeemAccountGroupEntity`模型包含以下统计字段：

| 字段名          | 类型   | 描述       |
| --------------- | ------ | ---------- |
| orderDate       | string | 订单日期   |
| groupId         | number | 分组ID     |
| groupName       | string | 分组名称   |
| count           | number | 账户数量   |
| sum             | number | 交易总额   |
| createdUserId   | string | 创建者ID   |
| createdUserName | string | 创建者名称 |

**Section sources**

- [kami-api-card-info-walmart-v1-v1-card-redeem-account-group-entity.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-v1-card-redeem-account-group-entity.ts)
- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

## 分页与数据过滤

所有列表查询API均支持统一的分页和数据过滤机制。

### 分页参数

| 参数名   | 类型   | 可选值            | 描述     |
| -------- | ------ | ----------------- | -------- |
| current  | number | -                 | 当前页码 |
| pageSize | number | 5,10,15,20,50,100 | 每页大小 |

### 通用过滤参数

- 账户名称过滤
- 用户ID过滤
- 分组ID过滤
- 创建者信息过滤
- 日期范围过滤

```mermaid
flowchart TD
Start([API请求]) --> CheckPage["验证分页参数"]
CheckPage --> PageValid{"参数有效?"}
PageValid --> |否| ReturnError["返回参数错误"]
PageValid --> |是| ApplyFilter["应用过滤条件"]
ApplyFilter --> QueryDB["查询数据库"]
QueryDB --> FormatResult["格式化结果"]
FormatResult --> AddPagination["添加分页信息"]
AddPagination --> ReturnSuccess["返回成功响应"]
ReturnError --> End([结束])
ReturnSuccess --> End
```

**Diagram sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)
- [kami-api-card-info-walmart-v1-list-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-list-req.ts)

**Section sources**

- [kami-api-card-info-walmart-v1-list-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-list-req.ts)

## 错误处理策略

API系统采用统一的错误响应格式，便于客户端进行错误处理。

### 常见错误码

- **200**: 请求成功
- **400**: 请求参数错误
- **404**: 资源未找到
- **500**: 服务器内部错误

### 错误响应结构

所有错误响应均包含错误代码、错误消息和可选的详细信息，帮助开发者快速定位问题。

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

## 常见问题排查

### 账户创建失败

**可能原因**:

- Cookie格式不正确或已过期
- 必填字段缺失
- 分组ID不存在

**解决方案**:

1. 验证Cookie的有效性
2. 检查请求参数完整性
3. 确认分组ID的正确性

### 状态检测超时

**可能原因**:

- 网络连接问题
- 账户服务响应缓慢
- API调用频率过高

**解决方案**:

1. 检查网络连接状态
2. 适当增加超时时间
3. 遵守API调用频率限制

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)

## 附录

### API端点列表

- 账户创建: POST /api/card/info/walmart/account/create
- 账户删除: DELETE /api/card/info/walmart/account/delete
- 状态检测: GET /api/card/info/walmart/account/status/detect
- 账户列表: GET /api/card/info/walmart/account/list
- 组列表: GET /api/card/info/walmart/group/list
- 组删除: DELETE /api/card/info/walmart/group/delete

### 数据类型说明

- 所有ID字段均为字符串类型
- 金额字段为数字类型，单位为分
- 日期字段采用ISO 8601格式

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
