# CDS数据接口文档

> ⚠️ **适用系统**：本文档仅针对**老系统**（`DataSource='source'`，导入走本接口、查询走 `api_search.php`，查询全量不过滤）。新老系统并行期的**新系统**（`GB_VAT_REGISTER_CDS_FILE`）契约见 [CDS数据对接新系统接口文档.md](./CDS数据对接新系统接口文档.md)。

## 概述

CDS系统提供两个主要API接口：

- **CDS数据导入API接口**：用于批量导入账号配置数据
- **CDS文件下载查询API接口**：用于查询递延文件下载记录

```
// domain地址
domain_url = http://43.138.180.224:8888/
```

> 注：签名验证当前已在服务端禁用（`sign` 字段保留但服务端不校验），调用时无需传签名字段。## 1. CDS数据导入API接口

### 基本信息

- **接口地址**: `/api_import.php`
- **请求方法**: `POST`
- **内容类型**: `application/json`
- **字符编码**: `UTF-8`

### 请求格式

#### 请求参数

| 参数名      | 类型    | 必填 | 描述                 |
| ----------- | ------- | ---- | -------------------- |
| records     | array   | 是   | 要导入的数据记录数组 |
| strict_mode | boolean | 否   | 严格模式，默认为0    |

#### records数组元素结构

| 字段名        | 类型   | 必填 | 长度限制    | 描述                                         |
| ------------- | ------ | ---- | ----------- | -------------------------------------------- |
| account_id    | string | 是   | 最大50字符  | CDS账号ID                                    |
| password      | string | 是   | 最大100字符 | CDS密码                                      |
| app_key       | string | 是   | 最大100字符 | 平台KEY                                      |
| account_alias | string | 是   | 最大50字符  | 账号别名标识，对应对接系统中本条数据唯一标识 |

#### 请求示例

```json
{
    "records": [
        {
            "account_id": "test001",
            "password": "password123",
            "app_key": "appkey456789",
            "account_alias": "data0000001"
        },
        {
            "account_id": "test002",
            "password": "password456",
            "app_key": "appkey987654",
            "account_alias": "data0000002"
            
        }
    ],
    "strict_mode": 0
}
```

### 响应格式

#### 成功响应

```json
{
    "code": 200,
    "msg": "导入完成",
    "data": {
        "total_records": 2,
        "success_count": 2,
        "error_count": 0,
        "errors": []
    }
}
```

#### 失败响应

```json
{
    "code": 0,
    "msg": "签名验证失败",
    "data": {}
}
```

#### 部分成功响应

```json
{
    "code": 200,
    "msg": "导入完成",
    "data": {
        "total_records": 3,
        "success_count": 2,
        "error_count": 1,
        "errors": [
            "记录3: account_id 'test003' 已存在"
        ]
    }
}
```

### 响应字段说明

#### 响应基本结构

| 字段名 | 类型   | 描述                   |
| ------ | ------ | ---------------------- |
| code   | int    | HTTP状态码 200 400 500 |
| msg    | string | 响应消息               |
| data   | object | 响应数据               |

#### data字段结构（成功时）

| 字段名        | 类型    | 描述           |
| ------------- | ------- | -------------- |
| total_records | integer | 总记录数       |
| success_count | integer | 成功导入记录数 |
| error_count   | integer | 失败记录数     |
| errors        | array   | 错误信息数组   |

### 错误码说明

| HTTP状态码 | 错误类型   | 描述                           |
| ---------- | ---------- | ------------------------------ |
| 200        | 成功       | 请求处理成功                   |
| 400        | 客户端错误 | 请求参数错误、签名验证失败等   |
| 500        | 服务器错误 | 数据库连接失败等服务器内部错误 |

### 常见错误信息

| 错误信息                    | 原因                         | 解决方案                   |
| --------------------------- | ---------------------------- | -------------------------- |
| "只支持POST请求"            | 使用了非POST方法             | 改用POST方法               |
| "JSON格式错误"              | 请求体不是有效的JSON         | 检查JSON格式               |
| "缺少签名字段"              | 未提供sign参数               | 添加sign参数               |
| "签名验证失败"              | 签名计算错误                 | 重新计算签名               |
| "缺少records字段或格式错误" | records参数缺失或非数组      | 提供正确的records数组      |
| "account_id不能为空"        | 记录中account_id为空         | 确保所有记录都有account_id |
| "account_id 'xxx' 已存在"   | 数据库中已存在相同account_id | 使用不同的account_id       |

### 严格模式说明

当设置`strict_mode: 1`时：

- 如果任何一条记录导入失败，将回滚所有操作
- 适用于要求数据完整性的场景

当设置`strict_mode: 0`（默认）时：

- 成功的记录会被保存，失败的记录会在errors数组中返回
- 适用于大批量导入，允许部分失败的场景
- 

## 2. CDS文件下载查询API接口

### 基本信息

- **接口地址**: `/api_search.php`
- **请求方法**: `GET`
- **内容类型**: `application/json`
- **字符编码**: `UTF-8`

### 请求参数

| 参数名        | 类型   | 必填 | 描述                                                 |
| ------------- | ------ | ---- | ---------------------------------------------------- |
| account_id    | string | 是   | CDS账号ID account_id和account_alias必须传1个以上参数 |
| account_alias | string | 是   | 账号别名标识，对应对接系统中本条数据唯一标识         |
| file_type     | string | 否   | 文件类型：`PVA`或`C79`，不传则查全部                 |
| start_date    | string | 否   | 开始年月（YYYYMM），筛选大于等于此日期               |
| end_date      | string | 否   | 结束年月（YYYYMM），筛选小于等于此日期               |
| sign          | string | 否   | 签名字符串                                           |

### 成功响应示例

```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 4,
            "account_id": "988354682688",
            "account_alias": "275437480",
            "file_type": "C79",
            "file_path": "https://vat-xxx/C79_988354682688_202507.pdf",
            "file_date": "202507",
            "created_time": "2025-09-01 14:30:07",
            "updated_time": "2025-09-01 14:30:07"
        }
    ]
}
```

### 失败响应示例

```json
{
    "code": 400,
    "msg": "account_id和account_alias必须传1个以上参数",
    "data": []
}
```

------

### 错误码说明

| HTTP状态码 | 错误类型   | 描述                                     |
| ---------- | ---------- | ---------------------------------------- |
| 200        | 成功       | 请求处理成功                             |
| 400        | 客户端错误 | 请求参数错误、缺少必填字段、签名不正确等 |
| 500        | 服务器错误 | 数据库连接失败、内部异常等               |