Upload local Office/PDF files as documents

# Upload a Local Office/PDF File as a Document

## URL

`/api/upload_office_doc/?token={token}`

## Request Method

`POST`

## Parameters

### Query Parameters

| Parameter Name | Data Type | Required | Description |
| ----- | ------ | ---- | -------------------- |
| token | string | Yes | User Token, used for identity verification and permission validation |

### Body Parameters (form-data)

| Parameter Name | Data Type | Required | Description |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| pid | integer | Yes | Project ID, the Office document will be created in the specified project |
| parent_doc | integer | No | Parent document ID, defaults to `0`, meaning it is created as a top-level document |
| file | file | Yes | The uploaded Office file, supporting Word, Excel, PowerPoint, and other Office formats supported by MrDoc |

## Response Result

| Field Name | Data Type | Description |
| ------ | --------------- | ------------------------------- |
| status | boolean | Whether the request succeeded, `true` means success, `false` means failure |
| data | object / string | Returns document information on success, error message on failure |

### Response Examples

**Success response:**

```json
{
    "status": true,
    "data": {
        "doc_id": 123,
        "filename": "2026/07/项目需求文档.docx"
    }
}
```

Returned field descriptions:

| Field Name | Data Type | Description |
| -------- | ------- | --------------------------- |
| doc_id | integer | The document ID after successful creation |
| filename | string | The relative path of the Office file in the MrDoc storage directory |

**Failure response:**

Invalid Token:

```json
{
    "status": false,
    "data": "token无效"
}
```

User has no permission:

```json
{
    "status": false,
    "data": "用户无权限操作"
}
```

Parameter error:

```json
{
    "status": false,
    "data": "参数错误"
}
```

No project permission:

```json
{
    "status": false,
    "data": "无文集权限"
}
```

No file selected:

```json
{
    "status": false,
    "data": "未选择文件"
}
```

File size exceeds limit:

```json
{
    "status": false,
    "data": "文件大小超出限制"
}
```

File format not supported:

```json
{
    "status": false,
    "data": "文件格式不支持"
}
```

System exception:

```json
{
    "status": false,
    "data": "系统异常"
}
```

---

## Permission Description

* The user must have Writer permission.
* The user must have the permission to add documents (`writer_value[1] == '1'`).
* The user must have the add permission for the target project, otherwise the API will return **"无文集权限"**.

---

## Python Example

```python
# coding: utf-8

import requests

# MrDoc address
base_url = 'http://192.168.1.2'

# User Token
token = '56968edc671b65265d20ab12631c7d5737edd0dab373e4e8e54a28f9'

url = f'{base_url}/api/upload_office_doc/?token={token}'

# Project ID to upload to
pid = 1

# Parent document ID (0 means top-level document)
parent_doc = 0

# Local Office file
office_file = '/path/to/项目需求文档.docx'

with open(office_file, 'rb') as f:
    files = {
        'file': f
    }
    data = {
        'pid': pid,
        'parent_doc': parent_doc
    }

resp = requests.post(url, data=data, files=files)
    print(resp.json())
```

---

## Error Code Description

| Error Message | Description |
| -------- | ----------------------------- |
| token无效 | The provided Token does not exist or has expired |
| 用户无权限操作 | The current user does not have permission to create documents |
| 参数错误 | The request is missing required parameters (such as `pid`) |
| 无文集权限 | The current user does not have the add permission for the target project |
| 未选择文件 | No Office file was uploaded in the request |
| 文件大小超出限制 | The uploaded file exceeds the maximum size allowed by the system or the file is empty |
| 文件格式不支持 | The uploaded file is not an Office document format supported by MrDoc |
| 系统异常 | An exception occurred while the server was processing the request |