> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 字段管理

> 管理文件类别下的普通字段和表格字段

> [!TIP]
>
> 字段是文件类别中用于定义抽取内容的核心配置。DocFlow 支持两种类型的字段：普通字段（在 result.fields 中）和表格字段（在 result.tables\[].fields 中）。本文介绍如何通过 API 管理这些字段。

## 获取字段列表

获取指定文件类别下的所有字段列表，包括普通字段和表格字段：

```bash curl icon=terminal wrap theme={null}
curl \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/list?workspace_id=<your-workspace-id>&category_id=<category-id>"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/list"

resp = requests.get(
    url=f"{host}{url}",
    params={
        "workspace_id": workspace_id,
        "category_id": category_id
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    fields = result.get("result", {}).get("fields", [])
    tables = result.get("result", {}).get("tables", [])

    print("普通字段：")
    for field in fields:
        print(f"  字段ID: {field.get('id')}, 名称: {field.get('name')}")

    print("\n表格字段：")
    for table in tables:
        print(f"  表格: {table.get('name')} (ID: {table.get('id')})")
        for field in table.get("fields", []):
            print(f"    字段ID: {field.get('id')}, 名称: {field.get('name')}")
else:
    print(f"获取失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "fields": [
      {
        "id": "field_123",
        "name": "发票代码",
        "description": "发票代码描述",
        "prompt": "请抽取发票代码"
      },
      {
        "id": "field_456",
        "name": "发票金额",
        "description": "发票金额描述"
      }
    ],
    "tables": [
      {
        "id": "table_789",
        "name": "货物明细",
        "description": "发票货物明细表",
        "fields": [
          {
            "id": "field_101",
            "name": "货物名称",
            "description": "货物名称描述"
          },
          {
            "id": "field_102",
            "name": "数量",
            "description": "货物数量"
          }
        ]
      }
    ]
  }
}
```

## 新增字段

在指定文件类别下批量新增字段，支持新增普通字段和表格字段：

### 新增普通字段

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "fields": [
      {
        "name": "发票号码",
        "description": "发票号码描述",
        "prompt": "请抽取发票号码",
        "use_prompt": true,
        "alias": ["Invoice Number", "编号"],
        "identity": "invoice_number",
        "multi_value": false
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_add"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/batch_add"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "fields": [
        {
            "name": "发票号码",
            "description": "发票号码描述",
            "prompt": "请抽取发票号码",
            "use_prompt": True,
            "alias": ["Invoice Number", "编号"],
            "identity": "invoice_number",
            "multi_value": False
        }
    ]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    field_ids = result.get("result", {}).get("field_ids", [])
    print(f"字段创建成功，IDs: {field_ids}")
else:
    print(f"创建失败: {result.get('msg')}")
```

### 新增表格字段

如果要在表格下新增字段，需要传入 `table_id` 参数：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "table_id": "<table-id>",
    "fields": [
      {
        "name": "单价",
        "description": "商品单价"
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_add"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
table_id = "<table-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/batch_add"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "table_id": table_id,  # 指定表格ID，创建表格字段
    "fields": [
        {
            "name": "单价",
            "description": "商品单价"
        }
    ]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    field_ids = result.get("result", {}).get("field_ids", [])
    print(f"表格字段创建成功，IDs: {field_ids}")
else:
    print(f"创建失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `table_id` (选填): 表格 ID。不传或为空：创建普通字段；传入表格ID：创建表格字段
* `fields` (必填): 字段数组，每个元素包含以下属性：
  * `name` (必填): 字段名称
  * `description` (选填): 字段描述
  * `prompt` (选填): 语义抽取提示词
  * `use_prompt` (选填): 是否使用语义提示词
  * `alias` (选填): 字段别名数组
  * `identity` (选填): 导出字段名
  * `multi_value` (选填): 是否多值抽取
  * `duplicate_value_distinct` (选填): 是否重复值去重（仅当 multi\_value 为 true 时有效）
  * `transform_settings` (选填): 转换配置

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "field_ids": ["field_new_123"]
  }
}
```

## 更新字段

批量更新指定字段的信息，支持更新普通字段和表格字段：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "fields": [
      {
        "field_id": "<field-id>",
        "name": "更新后的字段名称",
        "description": "更新后的描述",
        "prompt": "更新后的提示词"
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_update"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
field_id = "<field-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/batch_update"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "fields": [
        {
            "field_id": field_id,
            "name": "更新后的字段名称",
            "description": "更新后的描述",
            "prompt": "更新后的提示词"
        }
    ]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    print("字段更新成功")
else:
    print(f"更新失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `table_id` (选填): 表格 ID。对普通字段可不传；对表格字段需要传入其所属的表格ID
* `fields` (必填): 字段数组，每个元素包含以下属性：
  * `field_id` (必填): 字段 ID
  * 其他属性与创建字段相同（name、description、prompt 等）

> [!NOTE]
>
> 更新表格字段时，需要传入 `table_id` 参数指定该字段所属的表格。

## 删除字段

删除指定的字段，支持批量删除普通字段和表格字段：

### 删除普通字段

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "field_ids": ["field_123", "field_456"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/delete"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/delete"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "field_ids": ["field_123", "field_456"]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    print("普通字段删除成功")
else:
    print(f"删除失败: {result.get('msg')}")
```

### 删除表格字段

如果要删除表格字段，需要传入 `table_id` 参数：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "<category-id>",
    "table_id": "<table-id>",
    "field_ids": ["field_101", "field_102"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/delete"
```

```python Python icon=python expandable lines theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
table_id = "<table-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/category/fields/delete"

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "table_id": table_id,  # 指定表格ID，删除表格字段
    "field_ids": ["field_101", "field_102"]
}

resp = requests.post(
    url=f"{host}{url}",
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    print("表格字段删除成功")
else:
    print(f"删除失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `field_ids` (必填): 要删除的字段 ID 数组
* `table_id` (选填): 表格 ID。不传：删除普通字段；传入表格ID：删除表格字段

> [!WARNING]
>
> 删除字段后无法恢复，请谨慎操作。

## 字段配置说明

### 字段类型

* **普通字段**：存储在 `result.fields` 中的键值对字段
* **表格字段**：存储在 `result.tables[].fields` 中的表格列字段

### 字段属性

* **name**: 字段名称，必填
* **description**: 字段描述，选填
* **prompt**: 语义抽取提示词，用于指导 AI 进行字段抽取
* **use\_prompt**: 是否使用语义提示词
* **alias**: 字段别名数组，用于字段识别
* **identity**: 导出字段名，用于结果导出时的字段标识
* **multi\_value**: 是否多值抽取，支持一个字段抽取多个值
* **duplicate\_value\_distinct**: 重复值去重，仅当 multi\_value 为 true 时有效
* **transform\_settings**: 转换配置，支持日期时间、枚举、正则等转换

### 转换配置示例

```json theme={null}
{
  "transform_settings": {
    "type": "datetime",
    "datetime_settings": {
      "format": "yyyy-MM-dd HH:mm:ss"
    },
    "mismatch_action": {
      "mode": "warning",
      "default_value": ""
    }
  }
}
```

## 下一步

* 学习[表格管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/tables_management.md) - 管理文件类别下的表格
* 学习[样本管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/samples_management.md) - 管理文件类别的样本文件
* 返回[文件类别快速启动](https://docs-docflow.textin.com/docflow/cn/10-category-management/quickstart.md) - 查看文件类别基础操作


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.