字段管理 - Docflow API

字段是文件类别中用于定义抽取内容的核心配置。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>"

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

响应示例：

{
  "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>",
    "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"

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 参数：

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"

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 (选填): 转换配置

响应示例：

{
  "code": 200,
  "msg": "success",
  "result": {
    "field_ids": ["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>",
    "fields": [
      {
        "field_id": "<field-id>",
        "name": "更新后的字段名称",
        "description": "更新后的描述",
        "prompt": "更新后的提示词"
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_update"

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 等）

更新表格字段时，需要传入 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"

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 参数：

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"

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：删除表格字段

删除字段后无法恢复，请谨慎操作。

字段配置说明

字段类型

普通字段：存储在 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": ""
    }
  }
}

下一步

学习表格管理 - 管理文件类别下的表格
学习样本管理 - 管理文件类别的样本文件
返回文件类别快速启动 - 查看文件类别基础操作

​获取字段列表

​新增字段

​新增普通字段

​新增表格字段

​更新字段

​删除字段

​删除普通字段

​删除表格字段

​字段配置说明

​字段类型

​字段属性

​转换配置示例

​下一步

获取字段列表

新增字段

新增普通字段

新增表格字段

更新字段

删除字段

删除普通字段

删除表格字段

字段配置说明

字段类型

字段属性

转换配置示例

下一步