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

​
获取字段列表

获取指定文件类别下的所有字段列表，包括普通字段和表格字段： 
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>"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_id (必填): 文件类别 ID
响应示例： 
{
  "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": "货物数量"
          }
        ]
      }
    ]
  }
}

​
新增字段

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

​
新增普通字段

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>",
    "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/add"

​
新增表格字段

如果要在表格下新增字段，需要传入 table_id 参数： 
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>",
    "name": "单价",
    "description": "商品单价"
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/add"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_id (必填): 文件类别 ID
  • table_id (选填): 表格 ID。不传或为空：创建普通字段；传入表格ID：创建表格字段
  • name (必填): 字段名称
  • description (选填): 字段描述
  • prompt (选填): 语义抽取提示词
  • use_prompt (选填): 是否使用语义提示词
  • alias (选填): 字段别名数组
  • identity (选填): 导出字段名
  • multi_value (选填): 是否多值抽取
  • duplicate_value_distinct (选填): 是否重复值去重（仅当 multi_value 为 true 时有效）
  • transform_settings (选填): 转换配置
响应示例： 
{
  "code": 200,
  "msg": "success",
  "result": {
    "field_id": "field_new_123"
  }
}

​
更新字段

更新指定字段的信息，支持更新普通字段和表格字段： 
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_id": "<field-id>",
    "name": "更新后的字段名称",
    "description": "更新后的描述",
    "prompt": "更新后的提示词"
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/update"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_id (必填): 文件类别 ID
  • field_id (必填): 字段 ID
  • table_id (选填): 表格 ID。对普通字段可不传；对表格字段需要传入其所属的表格ID
  • 其他参数与创建字段相同
更新表格字段时，需要传入 table_id 参数指定该字段所属的表格。

​
删除字段

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

​
删除普通字段

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"

​
删除表格字段

如果要删除表格字段，需要传入 table_id 参数： 
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"
请求参数：
  • workspace_id (必填): 工作空间 ID
  • category_id (必填): 文件类别 ID
  • field_ids (必填): 要删除的字段 ID 数组
  • table_id (选填): 表格 ID。不传：删除普通字段；传入表格ID：删除表格字段
删除字段后无法恢复，请谨慎操作。

​
字段配置说明

​
字段类型

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

​
字段属性

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

​
转换配置示例

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

​
下一步