# 夸克网盘转存与分享API文档

本文档说明两个新创建的独立PHP API接口的使用方法。

---

## API 1: 夸克链接转存API

**文件名：** `quark_api_transfer.php`

### 功能描述
将夸克分享链接转存到指定账号的指定目录，支持通过**目录名称**或**目录ID**指定转存位置。

### 核心特性
- ✅ 支持通过目录名称自动查找或创建目录
- ✅ 支持通过目录ID直接指定转存位置
- ✅ 返回详细的转存文件信息
- ✅ 自动处理分享密码
- ✅ 完整的错误处理和日志记录

### 接口地址
```
POST /quark_api_transfer.php
```

### 请求参数
```json
{
    "cookie": "夸克网盘Cookie字符串（必填）",
    "share_url": "要转存的夸克分享链接（必填）",
    "target_folder_name": "目标文件夹名称（可选）",
    "target_folder_id": "目标文件夹ID（可选，默认'0'根目录）"
}
```

**参数说明：**
- `cookie`: 有效的夸克网盘Cookie
- `share_url`: 夸克分享链接，格式如 `https://pan.quark.cn/s/xxxxx`
- `target_folder_name`: 目标文件夹名称，如果不存在会自动创建
- `target_folder_id`: 目标文件夹的fid，'0'表示根目录

**重要规则：**
- `target_folder_name` 和 `target_folder_id` 至少提供一个
- 如果同时提供，优先使用 `target_folder_id`
- 如果都不提供，默认转存到根目录

### 成功响应示例
```json
{
    "success": true,
    "message": "转存成功",
    "data": {
        "share_name": "电影合集",
        "file_count": 5,
        "total_size": 5368709120,
        "size_formatted": "5.00 GB",
        "target_folder_id": "123456789",
        "target_folder_name": "我的电影",
        "saved_files": [
            {
                "fid": "987654321",
                "name": "电影1.mp4",
                "size": 1073741824,
                "size_formatted": "1.00 GB",
                "is_dir": false
            },
            {
                "fid": "987654322",
                "name": "电影2.mp4",
                "size": 1073741824,
                "size_formatted": "1.00 GB",
                "is_dir": false
            }
        ],
        "process_time": "3254.18ms"
    }
}
```

### 失败响应示例
```json
{
    "success": false,
    "message": "Cookie无效：Cookie已过期或无效"
}
```

### 使用示例

#### 示例1：转存到根目录
```bash
curl -X POST http://localhost:8000/quark_api_transfer.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123"
  }'
```

#### 示例2：转存到指定名称的文件夹（自动创建）
```bash
curl -X POST http://localhost:8000/quark_api_transfer.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123",
    "target_folder_name": "我的收藏"
  }'
```

#### 示例3：转存到指定ID的文件夹
```bash
curl -X POST http://localhost:8000/quark_api_transfer.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123",
    "target_folder_id": "123456789"
  }'
```

#### PHP调用示例
```php
<?php
$url = 'http://localhost:8000/quark_api_transfer.php';
$data = [
    'cookie' => 'your_cookie_here',
    'share_url' => 'https://pan.quark.cn/s/abc123',
    'target_folder_name' => '我的电影'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    echo "转存成功！\n";
    echo "分享名称: {$result['data']['share_name']}\n";
    echo "文件数量: {$result['data']['file_count']}\n";
    echo "总大小: {$result['data']['size_formatted']}\n";
    echo "转存到: {$result['data']['target_folder_name']}\n";
} else {
    echo "转存失败: {$result['message']}\n";
}
?>
```

#### JavaScript调用示例
```javascript
fetch('http://localhost:8000/quark_api_transfer.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cookie: 'your_cookie_here',
        share_url: 'https://pan.quark.cn/s/abc123',
        target_folder_name: '我的电影'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('转存成功！');
        console.log('分享名称:', data.data.share_name);
        console.log('文件数量:', data.data.file_count);
        console.log('总大小:', data.data.size_formatted);
    } else {
        console.error('转存失败:', data.message);
    }
});
```

#### Python调用示例
```python
import requests
import json

url = 'http://localhost:8000/quark_api_transfer.php'
data = {
    'cookie': 'your_cookie_here',
    'share_url': 'https://pan.quark.cn/s/abc123',
    'target_folder_name': '我的电影'
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    print("转存成功！")
    print(f"分享名称: {result['data']['share_name']}")
    print(f"文件数量: {result['data']['file_count']}")
    print(f"总大小: {result['data']['size_formatted']}")
else:
    print(f"转存失败: {result['message']}")
```

---

## API 2: 文件/文件夹分享API

**文件名：** `quark_api_share.php`

### 功能描述
创建夸克网盘文件或文件夹的分享链接，支持通过**文件名称**或**文件ID**指定要分享的对象。

### 核心特性
- ✅ 支持通过文件名称查找并分享
- ✅ 支持通过文件ID直接分享
- ✅ 支持设置分享有效期（永久/1天/7天/30天）
- ✅ 支持在指定目录中查找文件
- ✅ 同时支持文件和文件夹分享

### 接口地址
```
POST /quark_api_share.php
```

### 请求参数
```json
{
    "cookie": "夸克网盘Cookie字符串（必填）",
    "file_name": "要分享的文件/文件夹名称（可选）",
    "file_id": "要分享的文件/文件夹ID（可选）",
    "parent_fid": "父目录ID（可选，默认'0'根目录）",
    "validity": "有效期（可选，默认'1'）"
}
```

**参数说明：**
- `cookie`: 有效的夸克网盘Cookie
- `file_name`: 要分享的文件或文件夹名称
- `file_id`: 要分享的文件或文件夹的fid
- `parent_fid`: 在哪个目录中查找文件（仅当使用file_name时有效）
- `validity`: 分享有效期
  - `1`: 永久有效（默认）
  - `2`: 1天有效
  - `3`: 7天有效
  - `4`: 30天有效

**重要规则：**
- `file_name` 和 `file_id` 至少提供一个
- 如果同时提供，优先使用 `file_id`
- 使用 `file_name` 时，会在 `parent_fid` 指定的目录中查找

### 成功响应示例
```json
{
    "success": true,
    "message": "分享创建成功",
    "data": {
        "file_name": "我的电影.mp4",
        "file_id": "987654321",
        "file_size": 1073741824,
        "size_formatted": "1.00 GB",
        "is_dir": false,
        "share_url": "https://pan.quark.cn/s/xyz789",
        "share_pwd": "abcd",
        "validity_period": "永久有效",
        "validity_type": 1,
        "process_time": "2156.34ms"
    }
}
```

### 失败响应示例
```json
{
    "success": false,
    "message": "未找到名称为 '我的电影.mp4' 的文件或文件夹"
}
```

### 使用示例

#### 示例1：通过文件ID分享
```bash
curl -X POST http://localhost:8000/quark_api_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "file_id": "987654321",
    "validity": "1"
  }'
```

#### 示例2：通过文件名称分享（根目录）
```bash
curl -X POST http://localhost:8000/quark_api_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "file_name": "我的电影.mp4",
    "validity": "3"
  }'
```

#### 示例3：通过文件名称分享（指定目录）
```bash
curl -X POST http://localhost:8000/quark_api_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "file_name": "电影1.mp4",
    "parent_fid": "123456789",
    "validity": "2"
  }'
```

#### PHP调用示例
```php
<?php
$url = 'http://localhost:8000/quark_api_share.php';
$data = [
    'cookie' => 'your_cookie_here',
    'file_name' => '我的电影.mp4',
    'validity' => '1'  // 永久有效
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    echo "分享创建成功！\n";
    echo "文件名: {$result['data']['file_name']}\n";
    echo "分享链接: {$result['data']['share_url']}\n";
    echo "分享密码: {$result['data']['share_pwd']}\n";
    echo "有效期: {$result['data']['validity_period']}\n";
} else {
    echo "分享失败: {$result['message']}\n";
}
?>
```

#### JavaScript调用示例
```javascript
fetch('http://localhost:8000/quark_api_share.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cookie: 'your_cookie_here',
        file_name: '我的电影.mp4',
        validity: '1'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('分享创建成功！');
        console.log('分享链接:', data.data.share_url);
        console.log('分享密码:', data.data.share_pwd);
        console.log('有效期:', data.data.validity_period);
    } else {
        console.error('分享失败:', data.message);
    }
});
```

#### Python调用示例
```python
import requests
import json

url = 'http://localhost:8000/quark_api_share.php'
data = {
    'cookie': 'your_cookie_here',
    'file_name': '我的电影.mp4',
    'validity': '1'  # 永久有效
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    print("分享创建成功！")
    print(f"文件名: {result['data']['file_name']}")
    print(f"分享链接: {result['data']['share_url']}")
    print(f"分享密码: {result['data']['share_pwd']}")
    print(f"有效期: {result['data']['validity_period']}")
else:
    print(f"分享失败: {result['message']}")
```

---

## 组合使用示例

### 场景：转存后立即分享

```php
<?php
// 1. 先转存
$transfer_url = 'http://localhost:8000/quark_api_transfer.php';
$transfer_data = [
    'cookie' => 'your_cookie_here',
    'share_url' => 'https://pan.quark.cn/s/abc123',
    'target_folder_name' => '我的收藏'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $transfer_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($transfer_data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$transfer_response = curl_exec($ch);
curl_close($ch);

$transfer_result = json_decode($transfer_response, true);

if ($transfer_result['success']) {
    echo "转存成功！\n";
    
    // 获取第一个转存的文件
    $first_file = $transfer_result['data']['saved_files'][0];
    $file_id = $first_file['fid'];
    
    // 2. 创建分享链接
    $share_url = 'http://localhost:8000/quark_api_share.php';
    $share_data = [
        'cookie' => 'your_cookie_here',
        'file_id' => $file_id,
        'validity' => '1'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $share_url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($share_data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $share_response = curl_exec($ch);
    curl_close($ch);
    
    $share_result = json_decode($share_response, true);
    
    if ($share_result['success']) {
        echo "分享创建成功！\n";
        echo "新分享链接: {$share_result['data']['share_url']}\n";
        echo "分享密码: {$share_result['data']['share_pwd']}\n";
    }
}
?>
```

---

## 部署说明

### 方式一：使用Apache/Nginx
将两个PHP文件放置在Web服务器的文档根目录下即可访问。

### 方式二：使用PHP内置服务器（开发测试）
```bash
# 在项目目录下运行
cd c:\Users\Administrator\Desktop\quark1.1
php -S localhost:8000

# 然后可以通过以下地址访问
# http://localhost:8000/quark_api_transfer.php
# http://localhost:8000/quark_api_share.php
```

---

## 错误码说明

| HTTP状态码 | 说明 |
|-----------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误（Cookie为空、链接格式错误等） |
| 401 | Cookie无效或已过期 |
| 404 | 未找到指定的文件或文件夹 |
| 405 | 请求方法错误（仅支持POST） |
| 500 | 服务器内部错误 |

---

## 常见问题

### Q1: 如何获取Cookie？
A: 使用浏览器登录夸克网盘后，在开发者工具的Network标签页查看请求头中的Cookie值。

### Q2: 转存时如何创建多层目录？
A: 当前版本仅支持在根目录下创建或查找文件夹。如需多层目录，建议先手动创建，然后使用`target_folder_id`指定。

### Q3: 如何分享文件夹？
A: 与分享文件完全相同，只需提供文件夹的`file_name`或`file_id`即可。

### Q4: 分享链接多久失效？
A: 根据`validity`参数设置：
- `1`: 永久有效
- `2`: 1天后失效
- `3`: 7天后失效
- `4`: 30天后失效

### Q5: 同名文件如何处理？
A: 使用`file_name`查找时，会返回第一个匹配的文件。建议使用`file_id`精确指定。

---

## 注意事项

1. **Cookie安全**：Cookie包含敏感信息，请勿在不安全的环境中传输
2. **HTTPS推荐**：生产环境建议使用HTTPS协议
3. **跨域支持**：两个API都已启用CORS，支持跨域调用
4. **并发限制**：建议控制API调用频率，避免被夸克限制
5. **日志记录**：所有API都会记录详细日志到PHP错误日志中
6. **文件夹创建**：自动创建的文件夹仅在根目录下
7. **分享密码**：有些分享可能没有密码（显示"无"）

---

---

## API 3: 转存并分享一体化API

**文件名：** `quark_api_transfer_share.php`

### 功能描述
将夸克分享链接转存到指定目录，转存完成后自动创建新的分享链接，一步完成转存和分享操作。

### 核心特性
- ✅ 一次请求完成转存和分享两个操作
- ✅ 支持通过目录名或目录ID指定转存位置
- ✅ 自动等待并获取转存后的文件
- ✅ 支持自定义新分享的标题和有效期
- ✅ 返回完整的转存和分享信息
- ✅ 智能容错处理（转存成功但分享失败时返回部分结果）

### 接口地址
```
POST /quark_api_transfer_share.php
```

### 请求参数
```json
{
    "cookie": "夸克网盘Cookie字符串（必填）",
    "share_url": "要转存的夸克分享链接（必填）",
    "target_folder_name": "目标文件夹名称（可选）",
    "target_folder_id": "目标文件夹ID（可选，默认'0'根目录）",
    "validity": "新分享的有效期（可选，1-4，默认1）",
    "share_title": "新分享的标题（可选，默认使用原分享名称）"
}
```

**参数说明：**
- `cookie`: 有效的夸克网盘Cookie
- `share_url`: 要转存的夸克分享链接
- `target_folder_name`: 转存目标文件夹名称
- `target_folder_id`: 转存目标文件夹ID
- `validity`: 新分享的有效期（1=永久，2=1天，3=7天，4=30天）
- `share_title`: 自定义新分享的标题

**重要规则：**
- `target_folder_name` 和 `target_folder_id` 至少提供一个
- 如果同时提供，优先使用 `target_folder_id`
- 如果都不提供，默认转存到根目录

### 成功响应示例
```json
{
    "success": true,
    "message": "转存并分享成功",
    "data": {
        "transfer": {
            "share_name": "电影合集",
            "file_count": 5,
            "total_size": 5368709120,
            "size_formatted": "5.00 GB",
            "target_folder_id": "123456789",
            "target_folder_name": "我的收藏",
            "saved_files": [
                {
                    "fid": "987654321",
                    "name": "电影1.mp4",
                    "size": 1073741824,
                    "size_formatted": "1.00 GB",
                    "is_dir": false
                }
            ]
        },
        "share": {
            "file_name": "电影1.mp4",
            "file_id": "987654321",
            "file_size": 1073741824,
            "size_formatted": "1.00 GB",
            "is_dir": false,
            "share_url": "https://pan.quark.cn/s/newxyz123",
            "share_pwd": "efgh",
            "validity_period": "永久有效",
            "validity_type": 1
        },
        "process_time": "8756.42ms"
    }
}
```

### 部分成功响应示例
转存成功但分享失败时的响应（HTTP 206）：
```json
{
    "success": false,
    "message": "转存成功，但分享创建失败：轮询任务超时",
    "data": {
        "transfer": {
            "share_name": "电影合集",
            "file_count": 5,
            "total_size": 5368709120,
            "size_formatted": "5.00 GB",
            "target_folder_id": "123456789",
            "target_folder_name": "我的收藏",
            "saved_files": [...]
        },
        "share": null
    }
}
```

### 失败响应示例
```json
{
    "success": false,
    "message": "转存失败：分享内容为空"
}
```

### 使用示例

#### 示例1：基本使用（转存到根目录）
```bash
curl -X POST http://localhost:8000/quark_api_transfer_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123"
  }'
```

#### 示例2：转存到指定文件夹并设置有效期
```bash
curl -X POST http://localhost:8000/quark_api_transfer_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123",
    "target_folder_name": "我的收藏",
    "validity": "3"
  }'
```

#### 示例3：使用目录ID和自定义标题
```bash
curl -X POST http://localhost:8000/quark_api_transfer_share.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "share_url": "https://pan.quark.cn/s/abc123",
    "target_folder_id": "123456789",
    "validity": "1",
    "share_title": "精选电影合集"
  }'
```

#### PHP调用示例
```php
<?php
$url = 'http://localhost:8000/quark_api_transfer_share.php';
$data = [
    'cookie' => 'your_cookie_here',
    'share_url' => 'https://pan.quark.cn/s/abc123',
    'target_folder_name' => '我的收藏',
    'validity' => '1',
    'share_title' => '精选资源'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    echo "操作成功！\n";
    echo "原分享: {$result['data']['transfer']['share_name']}\n";
    echo "文件数: {$result['data']['transfer']['file_count']}\n";
    echo "新分享链接: {$result['data']['share']['share_url']}\n";
    echo "分享密码: {$result['data']['share']['share_pwd']}\n";
} else {
    echo "操作失败: {$result['message']}\n";
}
?>
```

#### JavaScript调用示例
```javascript
fetch('http://localhost:8000/quark_api_transfer_share.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cookie: 'your_cookie_here',
        share_url: 'https://pan.quark.cn/s/abc123',
        target_folder_name: '我的收藏',
        validity: '1'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('操作成功！');
        console.log('原分享:', data.data.transfer.share_name);
        console.log('文件数:', data.data.transfer.file_count);
        console.log('新分享链接:', data.data.share.share_url);
        console.log('分享密码:', data.data.share.share_pwd);
    } else {
        console.error('操作失败:', data.message);
    }
});
```

#### Python调用示例
```python
import requests
import json

url = 'http://localhost:8000/quark_api_transfer_share.php'
data = {
    'cookie': 'your_cookie_here',
    'share_url': 'https://pan.quark.cn/s/abc123',
    'target_folder_name': '我的收藏',
    'validity': '1'
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    print("操作成功！")
    print(f"原分享: {result['data']['transfer']['share_name']}")
    print(f"文件数: {result['data']['transfer']['file_count']}")
    print(f"新分享链接: {result['data']['share']['share_url']}")
    print(f"分享密码: {result['data']['share']['share_pwd']}")
else:
    print(f"操作失败: {result['message']}")
```

### 工作流程

```
1. 验证Cookie
   ↓
2. 确定转存目录（查找或创建）
   ↓
3. 执行转存操作
   ↓
4. 等待3-7秒（确保文件同步）
   ↓
5. 获取转存后的文件信息
   ↓
6. 创建新的分享链接
   ↓
7. 返回完整结果
```

### 优势特点

| 特点 | 说明 |
|------|------|
| **一步到位** | 一次请求完成转存和分享，无需多次调用 |
| **智能等待** | 自动等待3-7秒确保文件同步完成 |
| **灵活配置** | 支持多种参数组合，满足不同需求 |
| **容错处理** | 转存成功但分享失败时也返回转存信息 |
| **详细信息** | 返回完整的转存和分享详情 |
| **自定义标题** | 支持自定义新分享的标题 |

### 注意事项

1. **等待时间**：API会在转存后自动等待3-7秒，确保文件信息同步
2. **分享对象**：默认分享转存的第一个文件，如需分享其他文件请使用分享API
3. **部分成功**：转存成功但分享失败时，会返回HTTP 206状态码和转存信息
4. **自定义标题**：如果提供`share_title`，会覆盖原分享名称
5. **目录优先级**：同时提供目录名和ID时，优先使用ID

---

## 三个API功能对比

| 功能 | 转存API | 分享API | 一体化API |
|------|---------|---------|----------|
| **转存分享链接** | ✅ | ❌ | ✅ |
| **创建分享链接** | ❌ | ✅ | ✅ |
| **自动等待同步** | ❌ | ❌ | ✅ |
| **一次完成** | ❌ | ❌ | ✅ |
| **支持目录名** | ✅ | ❌ | ✅ |
| **支持目录ID** | ✅ | ❌ | ✅ |
| **支持文件名** | ❌ | ✅ | ❌ |
| **支持文件ID** | ❌ | ✅ | ❌ |
| **自定义标题** | ❌ | ❌ | ✅ |
| **设置有效期** | ❌ | ✅ | ✅ |
| **推荐场景** | 仅转存 | 仅分享 | 转存+分享 |

---

## 版本信息

- **版本**: 1.0.0
- **创建日期**: 2025-10-26
- **作者**: AI Assistant
- **依赖**: PHP 7.0+, cURL扩展

---

## 更新日志

### v1.0.0 (2025-10-26)
- ✨ 初始版本发布
- ✨ 支持通过目录名或目录ID转存
- ✨ 支持通过文件名或文件ID分享
- ✨ 新增一体化转存并分享API
- ✨ 完整的错误处理和日志记录
- ✨ 详细的转存和分享信息返回