# 京东账户管理API

<cite>
**本文档引用的文件**  
- [card-jd-account.ts](file://src/api/card-jd-account.ts)
- [kami-api-card-info-jd-v1-jdaccount-create-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-create-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-update-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-update-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-delete-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-delete-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-list-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-list-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-res.ts)
- [kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts)
- [kami-api-card-info-jd-v1-jdconfig-get-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-get-res.ts)
- [kami-api-card-info-jd-v1-jdconfig-set-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-set-req.ts)
- [jd-account.ts](file://src/router/routes/modules/jd-account.ts)
</cite>

## 目录

1. [简介](#简介)
2. [核心功能概览](#核心功能概览)
3. [账户管理API接口](#账户管理api接口)
4. [批量操作接口](#批量操作接口)
5. [数据模型说明](#数据模型说明)
6. [错误处理与最佳实践](#错误处理与最佳实践)
7. [配置管理接口](#配置管理接口)

## 简介

京东账户管理API提供了一套完整的接口，用于管理京东账户的全生命周期操作。该系统支持账户的创建、更新、删除、状态检查和钱包信息查询等功能。开发者可以通过这些API实现自动化账户管理，包括批量添加Cookie、批量检查账户状态、获取账户列表等操作。系统还提供了详细的配置管理功能，允许调整账户行为和充值策略。

## 核心功能概览

京东账户管理API主要提供以下核心功能：

- 账户的增删改查操作
- 批量Cookie导入与状态检查
- 账户钱包信息查询
- 账户状态刷新
- 配置参数获取与设置
- 订单历史与统计信息查询

这些功能通过清晰的RESTful接口暴露，便于集成到各种应用场景中。

```mermaid
graph TD
A[京东账户管理API] --> B[账户管理]
A --> C[批量操作]
A --> D[配置管理]
A --> E[数据查询]
B --> B1[创建账户]
B --> B2[更新账户]
B --> B3[删除账户]
B --> B4[刷新状态]
C --> C1[批量添加Cookie]
C --> C2[批量检查状态]
D --> D1[获取配置]
D --> D2[设置配置]
E --> E1[获取账户列表]
E --> E2[查询钱包信息]
E --> E3[订单历史查询]
```

**Diagram sources**

- [jd-account.ts](file://src/router/routes/modules/jd-account.ts#L1-L47)

## 账户管理API接口

### 创建京东账户

用于创建新的京东账户，需要提供必要的账户信息。

**请求参数 (KamiApiCardInfoJdV1JDAccountCreateReq):**

- `cookie`: Cookie信息（必填）
- `name`: 账户别名
- `maxAmountLimit`: 最大充值限制
- `maxCountLimit`: 最大充值次数
- `remark`: 备注信息
- `status`: 账户状态

### 更新京东账户

用于更新现有京东账户的信息。

**请求参数 (KamiApiCardInfoJdV1JDAccountUpdateReq):**

- `id`: 账户ID（必填）
- `cookie`: Cookie信息（必填）
- `name`: 账户别名
- `maxAmountLimit`: 最大充值限制
- `maxCountLimit`: 最大充值次数
- `remark`: 备注信息
- `status`: 账户状态

### 删除京东账户

用于删除指定的京东账户。

**请求参数 (KamiApiCardInfoJdV1JDAccountDeleteReq):**

- `id`: 账户ID（必填）

### 刷新账户状态

用于刷新指定账户的状态信息。

**请求参数 (KamiApiCardInfoJdV1JDAccountRefreshStatusReq):**

- `id`: 账户ID（必填）

### 获取账户列表

用于查询京东账户列表，支持分页和筛选。

**请求参数 (KamiApiCardInfoJdV1JDAccountListReq):**

- `current`: 当前页码（必填）
- `pageSize`: 每页数量（必填）
- `name`: 账户名称筛选
- `nickName`: 用户昵称筛选
- `cookie`: Cookie信息筛选

**响应数据 (KamiApiCardInfoJdV1JDAccountListRes):**

- `total`: 总记录数
- `list`: 账户记录列表（KamiApiCardInfoJdV1JDAccountListRecord）

**Section sources**

- [kami-api-card-info-jd-v1-jdaccount-create-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-create-req.ts#L19-L56)
- [kami-api-card-info-jd-v1-jdaccount-update-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-update-req.ts#L19-L62)
- [kami-api-card-info-jd-v1-jdaccount-delete-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-delete-req.ts#L19-L26)
- [kami-api-card-info-jd-v1-jdaccount-refresh-status-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-refresh-status-req.ts#L19-L26)
- [kami-api-card-info-jd-v1-jdaccount-list-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-req.ts#L19-L50)
- [kami-api-card-info-jd-v1-jdaccount-list-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-res.ts#L23-L36)

## 批量操作接口

### 批量添加Cookie

支持批量导入京东账户的Cookie信息。

**请求参数 (KamiApiCardInfoJdV1JDAccountCookieBatchAddReq):**

- `list`: Cookie信息列表（KamiApiCardInfoJdV1JDAccountCookieBatchInfo）

### 批量检查Cookie状态

用于批量检查上传的Cookie文件中账户的状态。

**请求参数 (KamiApiCardInfoJdV1JDAccountCookieBatchCheckReq):**

- `file`: 上传的文件（必填）

**响应数据 (KamiApiCardInfoJdV1JDAccountCookieBatchCheckRes):**

- `msg`: 消息提示
- `list`: 检查结果列表（KamiApiCardInfoJdV1JDAccountCookieBatchInfo）

### 单个Cookie状态检查

用于检查单个Cookie的有效性。

**请求参数 (KamiApiCardInfoJdV1JDAccountCookieCheckReq):**

- `cookie`: Cookie信息（必填）

**响应数据 (KamiApiCardInfoJdV1JDAccountCookieCheckRes):**

- `username`: 用户名
- `nickname`: 昵称
- `balance`: 余额
- `isExist`: 是否已存在系统中
- `isAvailable`: 是否可用

```mermaid
sequenceDiagram
participant Client as 客户端
participant API as 京东账户API
participant System as 系统
Client->>API : 批量检查Cookie文件
API->>System : 解析文件并验证每个Cookie
loop 每个Cookie
System->>System : 验证Cookie有效性
System->>System : 检查账户是否存在
System->>System : 获取账户基本信息
end
System-->>API : 返回批量检查结果
API-->>Client : 返回包含详细信息的结果列表
```

**Diagram sources**

- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts#L23-L30)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts#L19-L26)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts#L23-L36)

**Section sources**

- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-add-req.ts#L23-L30)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-req.ts#L19-L26)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-check-res.ts#L23-L36)
- [kami-api-card-info-jd-v1-jdaccount-cookie-check-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-check-req.ts#L19-L26)
- [kami-api-card-info-jd-v1-jdaccount-cookie-check-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-check-res.ts#L19-L50)

## 数据模型说明

### KamiApiCardInfoJdV1JDAccountListRecord

账户列表记录数据模型，包含以下字段：

- `id`: 账户ID
- `name`: 账户名称
- `cookie`: Cookie信息
- `nickname`: 用户昵称
- `username`: 京东用户ID
- `status`: 状态（1.正常 0.禁用）
- `accountStatus`: 账号是否可用
- `balance`: 余额
- `effectiveBalance`: 有效充值余额
- `maxCountLimit`: 最大充值次数
- `maxAmountLimit`: 最大充值限制
- `amountTotalSum`: 账单所有统计金额
- `amountTodaySum`: 账单今日统计金额
- `remark`: 备注

### KamiApiCardInfoJdV1JDAccountCookieBatchInfo

批量操作中的账户信息模型，包含：

- `username`: 用户名
- `nickname`: 昵称
- `balance`: 余额
- `isExist`: 是否存在系统中
- `isAvailable`: 是否可用
- `name`: 别名
- `cookie`: Cookie信息
- `maxAmountLimit`: 最大充值限制
- `maxCountLimit`: 最大充值次数

### KamiApiCardInfoJdV1JDAccountWalletListRes

钱包信息列表响应模型：

- `total`: 总记录数
- `list`: 钱包历史记录列表（KamiInternalModelEntityV1CardRedeemAccountHistory）

```mermaid
classDiagram
class KamiApiCardInfoJdV1JDAccountListRecord {
+string id
+string name
+string cookie
+string nickname
+string username
+number status
+boolean accountStatus
+number balance
+number effectiveBalance
+number maxCountLimit
+number maxAmountLimit
+number amountTotalSum
+number amountTodaySum
+string remark
}
class KamiApiCardInfoJdV1JDAccountCookieBatchInfo {
+string username
+string nickname
+number balance
+boolean isExist
+boolean isAvailable
+string name
+string cookie
+number maxAmountLimit
+number maxCountLimit
}
class KamiApiCardInfoJdV1JDAccountWalletListRes {
+number total
+Array<KamiInternalModelEntityV1CardRedeemAccountHistory> list
}
KamiApiCardInfoJdV1JDAccountListRecord <|-- KamiApiCardInfoJdV1JDAccountCookieBatchInfo : "继承"
```

**Diagram sources**

- [kami-api-card-info-jd-v1-jdaccount-list-record.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-record.ts#L23-L162)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-info.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-info.ts#L19-L74)
- [kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts#L23-L36)

**Section sources**

- [kami-api-card-info-jd-v1-jdaccount-list-record.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-list-record.ts#L23-L162)
- [kami-api-card-info-jd-v1-jdaccount-cookie-batch-info.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-cookie-batch-info.ts#L19-L74)
- [kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdaccount-wallet-list-res.ts#L23-L36)

## 错误处理与最佳实践

### 错误处理策略

1. **输入验证**：确保所有必填字段都已提供，特别是Cookie和ID字段
2. **状态检查**：在执行操作前检查账户的当前状态
3. **批量操作容错**：批量操作中部分失败时，应返回详细的错误信息
4. **重试机制**：对于网络相关的错误，建议实现指数退避重试机制

### 最佳实践建议

1. **Cookie管理**：定期刷新Cookie以确保账户有效性
2. **分页查询**：对于列表查询，使用合理的分页大小避免性能问题
3. **批量操作**：优先使用批量接口处理大量数据，提高效率
4. **状态同步**：定期调用状态刷新接口保持账户信息最新
5. **错误日志**：记录详细的错误信息以便排查问题

## 配置管理接口

### 获取京东配置

获取京东账户相关的系统配置。

**响应数据 (KamiApiCardInfoJdV1JDConfigGetRes):**

- `isAllowDifferentAmount`: 是否允许金额异议充值
- `isAllowDifferentSucceedCallback`: 是否允许金额异议回调(充值成功)
- `isAllowDifferentFailCallback`: 是否允许金额异议回调(充值失败)
- `redeemCardMinAmount`: 充值卡最小充值金额
- `isAllowCompensatedCallback`: 是否允许补卡自动回调
- `redeemCardRate`: 充值卡充值速率

### 设置京东配置

更新京东账户相关的系统配置。

**请求参数 (KamiApiCardInfoJdV1JDConfigSetReq):**

- `isAllowDifferentAmount`: 是否允许金额异议充值（必填）
- `isAllowDifferentSucceedCallback`: 是否允许金额异议回调(充值成功)（必填）
- `isAllowDifferentFailCallback`: 是否允许金额异议回调(充值失败)（必填）
- `redeemCardMinAmount`: 账号单日最大充值次数（必填）
- `isAllowCompensatedCallback`: 是否允许补卡自动回调（必填）
- `redeemCardRate`: 充值卡充值速率（必填）

```mermaid
flowchart TD
A[开始] --> B[获取当前配置]
B --> C{需要修改配置?}
C --> |是| D[准备新配置参数]
C --> |否| E[结束]
D --> F[验证参数有效性]
F --> G[调用设置配置API]
G --> H{调用成功?}
H --> |是| I[获取更新后配置验证]
H --> |否| J[记录错误并重试]
J --> K{达到重试次数?}
K --> |是| L[通知管理员]
K --> |否| G
I --> M[配置更新完成]
M --> E
```

**Diagram sources**

- [kami-api-card-info-jd-v1-jdconfig-get-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-get-res.ts#L19-L56)
- [kami-api-card-info-jd-v1-jdconfig-set-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-set-req.ts#L19-L56)

**Section sources**

- [kami-api-card-info-jd-v1-jdconfig-get-res.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-get-res.ts#L19-L56)
- [kami-api-card-info-jd-v1-jdconfig-set-req.ts](file://src/api/generated/models/kami-api-card-info-jd-v1-jdconfig-set-req.ts#L19-L56)
