开放 API 接口参考

本文档介绍 ComPDF AI API 的认证方式、请求格式、参数、响应结构、任务状态、错误处理和结果获取规则。本手册列出的接口均使用 /api/v2 路径前缀，实际访问地址以当前私有化部署环境配置的 API 基地址为准。除特别说明外，时间字段使用 ISO 8601 格式；文档示例统一使用 UTC。

1. 服务地址与鉴权

开放 API 主地址：

text

<API_BASE_URL>/api/v2

鉴权请求头支持以下任一形式（服务端按优先顺序读取）：

http

Authorization: Bearer <YOUR_API_KEY>

http

X-API-Key: <YOUR_API_KEY>
Api-Key: <YOUR_API_KEY>

API Key 决定本次请求所属的组织。调用方不能通过请求参数覆盖组织身份。上传时可选传入 user_id 作为文件所有者；如果传入，该用户必须属于 API Key 对应组织。未传入时，文件使用组织级归属。

2. 接口总览

下表列出本版本对外开放的 23 个正式接口，按业务能力组织。文件、模板、批次、任务、抽取、结果和资产接口由 comidp_java 提供；提醒规则接口由 Python 提供。工作台 /api/idp/workflow/** 和旧版 /api/open/v1/** 别名不属于本文档。

方法	路径	能力
POST	`/api/v2/files/upload`	上传文件或 URL 并创建处理任务
DELETE	`/api/v2/files`	删除文件
PUT	`/api/v2/files/{fileId}/template`	修改文件模板并重新抽取
GET	`/api/v2/batches/{batchId}/tasks`	查询批次任务
POST	`/api/v2/tasks/{taskId}/retry`	重试失败任务
DELETE	`/api/v2/tasks/{taskId}`	取消未完成任务
GET	`/api/v2/templates`	获取模板列表
GET	`/api/v2/templates/{templateId}/fields`	获取模板字段
POST	`/api/v2/templates`	创建模板
PUT	`/api/v2/templates/{templateId}`	更新模板
DELETE	`/api/v2/templates/{templateId}`	删除模板
POST	`/api/v2/templates/{templateId}/sample`	更换模板样本
POST	`/api/v2/extract/{fileId}/fields`	增加自定义字段并重新抽取
GET	`/api/v2/tasks/{taskId}`	获取任务状态和处理结果
PUT	`/api/v2/tasks/{taskId}`	编辑或确认处理结果
GET	`/api/v2/classify/{taskId}/result`	获取分类结果
POST	`/api/v2/rules`	创建提醒规则
PUT	`/api/v2/rules/{ruleId}`	更新提醒规则
GET	`/api/v2/rules`	获取提醒规则列表
GET	`/api/v2/rules/{ruleId}`	获取提醒规则详情
PATCH	`/api/v2/rules/{ruleId}/status`	启用或停用提醒规则
DELETE	`/api/v2/rules/{ruleId}`	删除提醒规则
GET	`/api/v2/assets`	获取组织资产

3. 通用约定

3.1 通用响应结构

json

{
  "code": 200,
  "message": "success",
  "data": {}
}

客户端需要同时校验 HTTP 状态码和响应体中的 code。业务错误可能通过 HTTP 200 返回，具体原因以 code 和 message 为准。

json

{
  "code": 401,
  "message": "Open API authentication failed",
  "data": null
}

无业务数据返回的成功响应，其 data 字段为 null。

3.2 标识符

fileId：文件唯一标识。
taskId：处理任务唯一标识。重试或重新处理会创建新的任务 ID，并通过 originalTaskId 关联原任务。
batchId：一次上传产生的批次 ID，一个批次可包含多个文件任务。
模板列表返回的 id 就是模板 ID，后续路径参数 templateId 使用该值。

3.3 文件和批次状态

任务详情使用细粒度状态：pending_parsing、parsing、parsing_failed、pending_classification、classifying、classification_failed、pending_extraction、extracting、extraction_completed、extraction_failed、cancelled。列表查询可以使用 pending、processing、completed、failed、cancelled 等粗粒度筛选值。

批次状态：pending、processing、completed、failed、partial_failed、cancelled、empty。

3.4 模板字段结构

json

{
  "prompt": "Extract the invoice number. Return only the value.",
  "mapping": null,
  "aliases": [
    "Invoice No.",
    "Invoice Number"
  ]
}

keys 表示普通字段；tableHeaders 的结构为“表格名 → 列名 → 字段配置”。可选的 elementOrder 用于描述普通字段与表格的混合顺序。其 type 只能为 key 或 table，name 必须引用已声明的字段/表格；表格项还必须通过 columnOrder 列出全部列且不得重复。

3.5 调用与字段命名

本文所有请求地址均以 <API_BASE_URL>/api/v2 表示；<API_BASE_URL> 由私有化部署时的网关或反向代理配置决定。将 <YOUR_API_KEY>、<TEMPLATE_ID>、<FILE_ID> 等占位符替换为真实值即可调用。
multipart 请求参数使用 snake_case 命名；JSON 响应字段使用 camelCase 命名。
user_id 仅用于文件所有者校验，不能改变 API Key 的组织权限；user_email 仅作为上传来源信息保存。
除特别说明外，所有接口使用统一的 code、message、data 响应结构。

通用 GET 示例：

bash

curl --location '<API_BASE_URL>/api/v2/templates' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

通用 JSON 示例：

bash

curl --location --request PUT '<API_BASE_URL>/api/v2/tasks/<TASK_ID>' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"fields":{"invoice_no":"INV-001"},"confirm":true}'

3.6 可选参数的实际行为

接口	可选参数	传入时	不传时
`POST /files/upload`	`user_id`	校验其为当前组织有效用户后，作为文件所有者	使用 API Key 验证得到的 `org_id` 作为文件归属
`POST /files/upload`	`template_id`	直接使用当前组织可用的已启用模板（包括该组织可用的默认模板），跳过自动分类	在已启用的组织模板和该组织未禁用的默认模板中自动分类；无候选模板时上传失败
`POST /files/upload`	`metadata`	按 4.1 节规则持久化并透传 JSON 对象	不保存、不发送业务元数据
`POST /files/upload`	`user_email`	保存为上传来源留档字段	上传来源邮箱为空
`GET /templates`	`search` / `status`	按名称和 `active`/`inactive` 状态过滤	返回当前组织全部未删除模板
`POST /templates/{templateId}/sample`	`page`	保存调用方传入的样本页码	默认使用第 `1` 页
`DELETE /files`	`file_ids`、`date_range`、`metadata_conditions`	多类条件取并集；metadata 内多个键取 AND。条件有效但没有匹配文件时成功返回 `deletedCount:0`。	至少要提供一类条件，否则返回 400
`PUT /tasks/{taskId}`	`confirm`	`confirm:false` 仅保存不确认；异常字段仅供展示，不阻止确认	默认 `true`

status 只接受 active 或 inactive。调用方传入其他值时应返回参数错误，不应静默改变筛选语义。

4. 开放 API

4.1 概述

本章按业务能力说明对外开放接口：文件管理、任务管理、模板与文件处理、提醒规则管理和资产管理。请求地址统一使用 <API_BASE_URL>/api/v2，其中 <API_BASE_URL> 由私有化部署的网关或反向代理配置决定。

所有接口均使用第 1 节定义的 Service API Key 鉴权、通用请求头和响应结构。异步接口通过返回的 batchId、taskIds、fileId 或 taskId 跟踪处理进度；解析结果、抽取结果、一体化结果、输出配置和确认状态作为相关接口的请求字段或响应字段说明，不另设需求外的结果接口。

4.1.1 单接口说明格式

每个接口按以下顺序说明：基本信息（方法、地址、鉴权、Content-Type）、请求参数（Headers、Path、Query、Form-data 或 JSON body）、请求示例、成功响应（HTTP 状态、完整 JSON 和字段说明）以及接口特有约束。通用错误码、状态流转和资产规则集中在本章后文，单接口只列适用的规则。

4.2 文件管理

本节只包含文件上传、删除和文件模板类别调整三个正式能力。

4.2.1 上传文件

http

POST /api/v2/files/upload
Content-Type: multipart/form-data

参数	必填	说明
`file`	与 `url` 二选一	可重复传入，支持一个批次上传多个文件
`url`	与 `file` 二选一	可公网访问的文件 URL
`mode`	是	`VisualExtract` 或 `LayoutExtract`
`template_id`	否	指定模板后跳过自动分类
`metadata`	否	JSON 对象字符串；保存为文件/批次业务上下文，详见下方说明
`user_id`	否	文件所有者。传入时必须属于 API Key 对应组织；不传时使用组织级归属。
`user_email`	否	上传来源邮箱；仅留档，不参与用户校验、鉴权或通知

bash

curl --location '<API_BASE_URL>/api/v2/files/upload' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --form 'file=@"/path/invoice.pdf"' \
  --form 'mode="VisualExtract"' \
  --form 'template_id="<TEMPLATE_ID>"' \
  --form 'user_id="<USER_ID>"' \
  --form 'metadata="{\"order_no\":\"SO-1001\"}"'

json

{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_01",
    "fileIds": [
      "file_01"
    ],
    "taskIds": [
      "file_01"
    ],
    "uploadStatus": "processing"
  }
}

metadata 与 user_email 的行为

metadata 必须是 JSON 对象字符串。服务端保存并返回 JSON 对象；抽取事件、确认事件和 Webhook 事件也以 JSON 对象形式透传。

删除文件接口的 metadata_conditions 可对该对象做精确匹配：传入的每个键值都必须与保存值相同。非 JSON 对象虽然会被保存为原始文本，但不能可靠用于事件透传或 metadata_conditions 匹配。

metadata 不参与 API Key 鉴权、组织归属、模板选择、文件所有者判定或资产扣费。由于它可能被发送到提醒和 Webhook 流程，请勿放入密码、密钥或其他敏感信息。

user_email 仅保存为上传来源邮箱；不会用于组织判定、鉴权、通知收件人或文件权限控制。

4.2.2 删除文件

http

DELETE /api/v2/files
Content-Type: application/json

请求体至少提供一种条件：

json

{
  "file_ids": [
    "file_01",
    "file_02"
  ],
  "date_range": {
    "start": "2026-07-01T00:00:00",
    "end": "2026-07-31T23:59:59"
  },
  "metadata_conditions": {
    "project_id": "P-001"
  },
  "delete_permanently": false
}

响应 data 包含 deletedCount、failedCount、failedIds 和 failedReasons；其中 failedReasons 是“失败文件 ID → 服务端失败原因”的映射。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "deletedCount": 2,
    "failedCount": 0,
    "failedIds": [],
    "failedReasons": {}
  }
}

条件有效但没有任何匹配文件时，不视为参数错误，正常返回：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "deletedCount": 0,
    "failedCount": 0,
    "failedIds": [],
    "failedReasons": {}
  }
}

匹配范围包含当前组织内所有已记录 org_id 的文件（无论由页面还是 API Key 创建）；也包含历史上尚未记录 org_id、但文件所有者属于当前组织的文件。

4.2.3 修改文件模板类别

http

PUT /api/v2/files/{fileId}/template
Content-Type: application/json

json

{
  "template_id": "<TEMPLATE_ID>"
}

template_id 使用 GET /api/v2/templates 返回的真实模板 ID。该接口是文件模板类别调整的唯一正式路径；/api/v2/files/{fileId}/category 不作为对外兼容别名。修改模板后，服务端会清理旧抽取结果并创建新的处理任务；原任务与新任务之间应通过 originalTaskId 关联。

4.3 任务管理

本节统一说明批次任务查询、失败任务重试和未完成任务取消。任务状态、批次状态、重试条件、取消条件和配额预锁定规则适用于本节全部接口。

4.3.1 查询批次任务列表

http

GET /api/v2/batches/{batchId}/tasks?status=processing

status 可选：pending、processing、completed、failed、cancelled。任务正常流转为 pending → processing → completed/failed/cancelled；失败重试会保留原任务记录并创建新的处理任务。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_01",
    "batchStatus": "processing",
    "tasks": [
      {
        "taskId": "file_01",
        "fileId": "file_01",
        "fileName": "invoice.pdf",
        "status": "processing",
        "phase": "extracting",
        "confirmStatus": "pending",
        "metadata": {
          "order_no": "SO-1001"
        }
      }
    ]
  }
}

4.3.2 重新启动任务

http

POST /api/v2/tasks/{taskId}/retry

除已删除任务外，仅 parsing_failed、classification_failed 和 extraction_failed 允许重试。解析失败从解析阶段重新开始，分类失败重新执行分类，抽取失败从抽取阶段重新开始。已完成、处理中或已取消的任务不能重复重试。

重试会创建新的 taskId，并通过 originalTaskId 关联原任务。原任务的失败状态、错误信息和审计记录继续保留。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_02",
    "originalTaskId": "task_01",
    "fileId": "file_01",
    "status": "pending",
    "startPhase": "parsing"
  }
}

4.3.3 取消任务

http

DELETE /api/v2/tasks/{taskId}

只允许取消 pending 或 processing 任务。取消成功后任务状态变为 cancelled，尚未结算的资产预占应被释放；重复取消应保持幂等。

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.4 模板与文件处理

本节使用业务名称“模板与文件处理”，不使用内部 WorkFlow 作为章节名称。核心能力包括：获取模板列表、获取模板字段、创建模板、更新模板、删除模板、上传或更改模板样本、自定义字段抽取、获取文件处理结果、更新文件处理结果、获取文件分类和模板状态管理。解析结果、抽取结果、输出配置和结果确认均在相关接口中说明。

模板创建和更新时，keys、tableHeaders、elementOrder 共同构成输出配置；文件处理结果接口返回 parsingResult、extractionResult、layoutOutput 和字段异常信息；结果更新接口负责保存或确认最终结果。

本节的核心接口编号沿用接口总览。样本自动配置和模板测试是当前服务已实现的辅助能力，放在本节末尾单独标注，不计入 PRD 核心接口数量。

4.4.1 获取模板列表

http

GET /api/v2/templates?search=invoice&status=active

status 可选：active、inactive。响应为平铺数组，包含当前组织已发布的模板及系统默认模板；系统默认模板会按当前组织的启停记录投影其 status，已被当前组织停用的默认模板仍可通过 status=inactive 查询。模板主键字段为 id；source 为 organization 或 default，默认模板的 editable=false。

json

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "tpl_01",
      "name": "Invoice",
      "fileId": "sample_01",
      "page": 1,
      "status": 1,
      "source": "organization",
      "editable": true,
      "keys": {},
      "tableHeaders": {},
      "elementOrder": []
    },
    {
      "id": "13",
      "name": "身份证",
      "fileId": "acd5077b462d5a63943b1b2dfa963fdf",
      "status": 1,
      "source": "default",
      "editable": false,
      "keys": {},
      "tableHeaders": {}
    }
  ]
}

4.4.2 获取模板字段列表

http

GET /api/v2/templates/{templateId}/fields

json

{
  "code": 200,
  "message": "success",
  "data": {
    "keys": {
      "invoice_no": {
        "prompt": "Extract invoice number",
        "mapping": null,
        "aliases": []
      }
    },
    "tableHeaders": {},
    "elementOrder": []
  }
}

4.4.3 创建模板

创建模板所需的样本文件由当前模板创建接口按正式契约处理。

http

POST /api/v2/templates
Content-Type: application/json

json

{
  "name": "Invoice",
  "fileId": "sample_01",
  "page": 1,
  "keys": {
    "invoice_no": {
      "prompt": "Extract invoice number",
      "mapping": null,
      "aliases": []
    }
  },
  "tableHeaders": {},
  "elementOrder": [
    {
      "type": "key",
      "name": "invoice_no",
      "columnOrder": null
    }
  ]
}

name、样本 fileId 以及至少一个普通字段或表格字段必填。成功响应的 data 是模板 ID。

json

{
  "code": 200,
  "message": "success",
  "data": "tpl_01"
}

4.4.4 更新模板

http

PUT /api/v2/templates/{templateId}
Content-Type: application/json

请求体使用与创建模板相同的字段结构；已有样本 fileId 会保留。

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.4.5 删除模板

http

DELETE /api/v2/templates/{templateId}

执行逻辑删除，成功响应 data:null。

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.4.6 上传或更改模板样本

http

POST /api/v2/templates/{templateId}/sample
Content-Type: multipart/form-data

参数：file 必填；page 可选，默认 1。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "sampleFileId": "sample_02",
    "fileName": "invoice.pdf",
    "fileSize": 102400
  }
}

4.4.7 自定义字段抽取

http

POST /api/v2/extract/{fileId}/fields
Content-Type: application/json

json

{
  "keys": {
    "purchase_order": {
      "prompt": "Extract purchase order number",
      "mapping": null,
      "aliases": [
        "PO"
      ]
    }
  },
  "tableHeaders": {}
}

在文件现有模板快照中合并额外字段，并创建新的处理任务；原任务结果和新任务之间通过任务关联字段追踪。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "status": "pending"
  }
}

4.4.8 获取文件处理结果

http

GET /api/v2/tasks/{taskId}

返回任务状态、阶段、确认状态、输入、最终字段/表格结果、解析结果、异常字段、页数消耗和元数据。extractionResult 为最终抽取结果，parsingResult 为解析结果，fieldExceptionDetails 为异常字段数组。artifacts 返回解析 ZIP、抽取 JSON 和一体化 ZIP 的可用状态与下载地址。

结果可用性规则：

任务阶段	`parsingResult`	`extractionResult`	一体化 ZIP
解析中或解析失败	不可用	不可用	不可用
解析成功、抽取中	可用	不可用	不可用
抽取失败	可用	不可用	不可用
抽取成功	可用	可用	可用

因此，解析成功但抽取失败时，调用方仍可以获取解析结果；解析失败时不应返回可用的抽取结果。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "fileName": "invoice.pdf",
    "status": "completed",
    "phase": null,
    "confirmStatus": "pending",
    "metadata": {
      "order_no": "SO-1001"
    },
    "output": {
      "fields": {
        "invoice_no": "INV-001"
      },
      "tables": {},
      "orderedElements": []
    },
    "layoutOutput": null,
    "fieldExceptions": [],
    "input": {
      "fileId": "file_01",
      "templateId": "tpl_01",
      "templateName": "Invoice",
      "mode": "VisualExtract"
    },
    "consumption": {
      "pages": 1
    }
  }
}

4.4.9 更新文件处理结果

http

PUT /api/v2/tasks/{taskId}
Content-Type: application/json

json

{
  "fields": {
    "invoice_no": "INV-001-R"
  },
  "tables": {},
  "confirm": true
}

至少提供 fields 或 tables。只能修改已完成且未确认的任务；异常字段仅供展示，不阻止确认。

confirm 当前默认值为 true；如果只保存修改而不确认，必须显式传 false。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "fileName": "invoice.pdf",
    "status": "completed",
    "phase": null,
    "confirmStatus": "confirmed",
    "metadata": {
      "order_no": "SO-1001"
    },
    "error": null,
    "createdAt": "2026-07-22T08:00:00",
    "completedAt": "2026-07-22T08:05:00",
    "updateDate": "2026-07-22T08:05:00",
    "output": {
      "fields": {
        "invoice_no": "INV-001-R"
      },
      "tables": {},
      "orderedElements": []
    },
    "layoutOutput": null,
    "fieldExceptions": [],
    "input": {
      "fileId": "file_01",
      "templateId": "tpl_01",
      "templateName": "Invoice",
      "mode": "VisualExtract"
    },
    "consumption": {
      "pages": 1
    }
  }
}

4.4.10 获取文件分类

http

GET /api/v2/classify/{taskId}/result

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "status": "completed",
    "templateId": "tpl_01",
    "templateName": "Invoice",
    "confidence": null,
    "metadata": {}
  }
}

4.5 提醒规则管理

提醒规则由 Python 服务提供。公共路径和 Python 实际路径均为 /api/v2/rules/**；API Gateway 必须在通用 Java /api/v2/** 路由之前，将以下六个方法转发到 Python，并保留 API Key 请求头。浏览器工作台使用登录态的 /v1/reminder_rule/**，不能作为外部开放 API 的转发目标。

4.5.1 鉴权与组织隔离

支持以下任一请求头：

http

X-API-Key: <YOUR_API_KEY>
Api-Key: <YOUR_API_KEY>
Authorization: Bearer <YOUR_API_KEY>

Python 使用现有 Service API Key 服务验证密钥，从验证结果取得 org_id 和 api_key_id。调用方不能传入或覆盖 org_id、leader_id、user_id 等组织身份字段；所有规则查询、更新、启停和删除均限制在该 org_id 内，操作日志使用 api_key_id 记录。

4.5.2 请求模型

创建请求至少包含以下字段：

json

{
  "name": "Large invoice",
  "template_id": "tpl_01",
  "conditions": [
    {
      "field": "total_amount",
      "operator": "gt",
      "value": 10000,
      "logic": "AND"
    }
  ],
  "frequency": "on_extract_complete",
  "channels": [
    "in_app",
    "email"
  ],
  "recipients": {
    "members": [],
    "field_bindings": [],
    "webhook_ids": []
  },
  "title_template": "Invoice alert {file_name}",
  "content_template": "Total: {total_amount}"
}

frequency 支持 daily、hourly、on_extract_complete 和 on_result_confirm。channels 支持 in_app、email 和 webhook。条件的 logic 支持 AND、OR；条件判断、周期扫描、通知创建、邮件发送、Webhook 投递和重试由 Python 提醒规则服务负责。recipients.members 为空时，站内信和成员邮箱通知组织内有效成员；field_bindings 仅用于邮件动态收件人，非法邮箱会被跳过并记录原因。

4.5.3 接口与响应

方法	路径	说明
`POST`	`/api/v2/rules`	创建规则；成功 HTTP 201
`PUT`	`/api/v2/rules/{ruleId}`	更新提交的规则字段
`GET`	`/api/v2/rules?status=active`	获取规则列表；`status` 可选为 `active`/`inactive`
`GET`	`/api/v2/rules/{ruleId}`	获取规则完整配置
`PATCH`	`/api/v2/rules/{ruleId}/status`	请求体为 `{"status":"active"}` 或 `{"status":"inactive"}`
`DELETE`	`/api/v2/rules/{ruleId}`	永久删除；成功 HTTP 204 且无响应体

创建示例：

bash

curl --location '<API_BASE_URL>/api/v2/rules' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Large invoice",
    "template_id": "tpl_01",
    "conditions": [
      {"field": "total_amount", "operator": "gt", "value": 10000, "logic": "AND"}
    ],
    "frequency": "on_extract_complete",
    "channels": ["in_app", "email"],
    "recipients": {"members": [], "field_bindings": [], "webhook_ids": []},
    "title_template": "Invoice alert {file_name}",
    "content_template": "Total: {total_amount}"
  }'

创建成功响应：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rule_id": "rule_01",
    "name": "Large invoice",
    "status": "active",
    "created_at": "2026-07-27T06:12:43Z"
  }
}

列表成功响应：

json

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "rule_id": "rule_01",
      "name": "Large invoice",
      "template_id": "tpl_01",
      "status": "active",
      "channels": [
        "in_app",
        "email"
      ],
      "frequency": "on_extract_complete",
      "created_at": "2026-07-27T06:12:43Z",
      "updated_at": "2026-07-27T06:12:43Z"
    }
  ]
}

详情和更新响应在上述公共字段基础上返回 conditions、recipients、title_template 和 content_template。状态变更至少返回 rule_id 和 status：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rule_id": "rule_01",
    "status": "inactive"
  }
}

所有公开时间字段均为 ISO 8601 UTC 格式并以 Z 结尾。响应使用 rule_id、created_at、updated_at，不会暴露 org_id、created_by、updated_by、create_time 或 update_time 等内部字段。

4.5.4 错误与业务复用

HTTP 状态	场景
400	请求参数、条件、渠道、频率或收件人配置不合法
401	API Key 缺失、无效、停用或过期
404	规则不存在或不属于当前 API Key 的组织
409	同组织规则名称冲突或其他资源状态冲突

规则事件仍由 Java 通过内部 HMAC 接口 POST /v1/reminder_rule/events/trigger 发送，不使用 Service API Key。Python 复用现有提醒规则 Service，负责条件判断、事件/周期触发、站内信、邮件、Webhook、投递记录和去重；成功完整更新规则后，仅清除该组织该规则的 24 小时去重记录，状态 PATCH 不重置去重记录，删除规则同时删除其去重记录。

4.6 资产管理

4.6.1 获取资产信息

http

GET /api/v2/assets

返回账号类型、有效期和各产品资产。抽取产品重点字段为 used、withholding、remaining、total。

json

{
  "code": 200,
  "message": "success",
  "data": {
    "accountType": "paid",
    "expireTime": null,
    "products": [
      {
        "productType": "extract",
        "productName": "Extraction",
        "unit": "page",
        "used": 20,
        "withholding": 5,
        "remaining": 975,
        "total": 1000,
        "progress": 2
      }
    ]
  }
}

5. 全接口请求参数字段索引

所有接口均须携带第 1 节定义的 API Key 请求头。下表补齐每条接口的路径、查询、表单和 JSON 请求体字段；“无”表示除路径参数和鉴权头外不接收业务请求参数。路径字段均为 URL 编码后的资源 ID。

接口	位置	字段	必填	详细说明
1 `POST /files/upload`	form	`file`	与 `url` 二选一	一个或多个上传文件；与 `url` 不可同时为空。
1 `POST /files/upload`	form	`url`	与 `file` 二选一	服务端可访问的文件地址。
1 `POST /files/upload`	form	`mode`	是	`VisualExtract` 或 `LayoutExtract`。
1 `POST /files/upload`	form	`template_id`	否	当前组织内启用模板；传入后跳过自动分类。
1 `POST /files/upload`	form	`metadata`	否	JSON 对象字符串；用于业务透传，不影响鉴权或资产。
1 `POST /files/upload`	form	`user_id`、`user_email`	否	前者须属于当前组织并作为文件所有者；后者仅作上传来源留档。
2 `DELETE /files`	body	`file_ids`	至少一类条件	待删除文件 ID 数组；与其他删除条件取并集。
2 `DELETE /files`	body	`date_range.start`、`date_range.end`	否	ISO 8601 起止时间；按上传时间筛选。
2 `DELETE /files`	body	`metadata_conditions`	否	JSON 对象；其中所有键值须精确匹配。
2 `DELETE /files`	body	`delete_permanently`	否	布尔值；`true` 为永久删除，缺省按服务端默认策略处理。
3 `PUT /files/{fileId}/template`	path	`fileId`	是	要重新指定模板的文件 ID。
3 `PUT /files/{fileId}/template`	body	`template_id`	是	`GET /templates` 返回的真实模板 ID。
4 `GET /batches/{batchId}/tasks`	path	`batchId`	是	上传返回的批次 ID。
4 `GET /batches/{batchId}/tasks`	query	`status`	否	`pending`、`processing`、`completed`、`failed` 或 `cancelled`。
5 `POST /tasks/{taskId}/retry`	path	`taskId`	是	仅 `parsing_failed`、`classification_failed`、`extraction_failed` 任务可重试。
5 `POST /tasks/{taskId}/retry`	body/query	无	否	无业务请求体或查询参数。
6 `DELETE /tasks/{taskId}`	path	`taskId`	是	仅 `pending` 或 `processing` 任务可取消。
6 `DELETE /tasks/{taskId}`	body/query	无	否	无业务请求体或查询参数。
7 `GET /templates`	query	`search`	否	按模板名称模糊筛选。
7 `GET /templates`	query	`status`	否	仅 `active` 或 `inactive`。
8 `GET /templates/{templateId}/fields`	path	`templateId`	是	模板 ID。
8 `GET /templates/{templateId}/fields`	body/query	无	否	无业务请求体或查询参数。
9 `POST /templates`	body	`name`、`fileId`、`page`	`name`、`fileId` 是	模板名称、样本文件 ID、样本页码；`page` 缺省为 1。
9 `POST /templates`	body	`keys`、`tableHeaders`	至少一种	普通字段或表格字段定义；字段配置见 3.4 节。
9 `POST /templates`	body	`elementOrder`	否	混合展示顺序；每项含 `type`、`name`，表格项还含 `columnOrder`。
10 `PUT /templates/{templateId}`	path	`templateId`	是	要更新的模板 ID。
10 `PUT /templates/{templateId}`	body	`name`、`fileId`、`page`、`keys`、`tableHeaders`、`elementOrder`	否	字段语义同创建模板；未提供 `fileId` 时保留现有样本。
11 `DELETE /templates/{templateId}`	path	`templateId`	是	要逻辑删除的模板 ID。
11 `DELETE /templates/{templateId}`	body/query	无	否	无业务请求体或查询参数。
12 `POST /templates/{templateId}/sample`	path	`templateId`	是	要替换样本的模板 ID。
12 `POST /templates/{templateId}/sample`	form	`file`、`page`	`file` 是	样本文件和从 1 开始的页码；`page` 缺省为 1。
13 `POST /extract/{fileId}/fields`	path	`fileId`	是	需要补充字段并重新抽取的文件 ID。
13 `POST /extract/{fileId}/fields`	body	`keys`、`tableHeaders`	至少一种	与现有模板快照合并的普通字段或表格字段。
14 `GET /tasks/{taskId}`	path	`taskId`	是	要查询处理状态和结果的任务 ID。
14 `GET /tasks/{taskId}`	body/query	无	否	无业务请求体或查询参数。
15 `PUT /tasks/{taskId}`	path	`taskId`	是	已完成且尚未确认的任务 ID。
15 `PUT /tasks/{taskId}`	body	`fields`、`tables`	至少一种	最终抽取结果中的普通字段对象或表格对象。
15 `PUT /tasks/{taskId}`	body	`confirm`	否	缺省为 `true`；`false` 只保存不确认。
16 `GET /classify/{taskId}/result`	path	`taskId`	是	分类任务 ID。
16 `GET /classify/{taskId}/result`	body/query	无	否	无业务请求体或查询参数。
规则 1 `POST /rules`	body	`name`、`template_id`、`conditions`、`frequency`、`channels`、`recipients`、`title_template`、`content_template`	是	创建提醒规则；成功 HTTP 201。
规则 2 `PUT /rules/{ruleId}`	path/body	`ruleId`；任意规则字段	`ruleId` 是	更新提交的规则字段；成功返回完整公共规则 DTO。
规则 3 `GET /rules`	query	`status`	否	`active` 或 `inactive`；不传返回当前组织全部规则。
规则 4 `GET /rules/{ruleId}`	path	`ruleId`	是	获取当前 API Key 组织内的规则详情。
规则 5 `PATCH /rules/{ruleId}/status`	path/body	`ruleId`、`status`	是	`status` 为 `active` 或 `inactive`。
规则 6 `DELETE /rules/{ruleId}`	path	`ruleId`	是	永久删除；成功 HTTP 204 且无响应体。
23 `GET /assets`	body/query	无	否	无业务请求体、路径或查询参数。

6. 推荐调用流程与错误处理

典型自动化流程：

GET /api/v2/templates 取得模板 id；如需创建模板，先上传样本，再创建模板。
POST /api/v2/files/upload 上传一个或多个文件。可传当前组织内的 user_id；不传时默认使用验证得到的 org_id。保存返回的 batchId 和 taskIds。
多文件场景用批次接口查看整体进度；单文件场景轮询 GET /api/v2/tasks/{taskId}。
status=completed 后读取 extractionResult；如果任务失败，读取 error 和 fieldExceptionDetails，修复原因后仅对允许重试的失败阶段调用重试接口。
如需人工修订，使用 PUT /api/v2/tasks/{taskId}；要只保存不确认，请传 confirm:false。

常见错误：

code	含义/处理建议
400	参数、状态或模板配置不合法；读取 `message` 修正请求
401	API Key 缺失或无效
403	调用方显式指定的上传 `user_id` 不属于 API Key 对应组织
404	资源不存在，或资源不属于 API Key 对应组织
409	当前状态不允许操作或并发版本冲突
415	文件扩展名不受支持

不要只判断 HTTP 状态码。客户端必须同时检查响应体中的业务 code；错误详情以 message 和 data 为准。调用方还应为轮询、重试和下载请求设置超时，并根据 taskId、batchId 和资源 ID 实现幂等与分页处理。

缺少 Query/Form 参数时会明确返回字段名，例如：

json

{
  "code": 400,
  "message": "Required parameter 'mode' is missing",
  "data": {
    "mode": "required"
  }
}

缺少 multipart 文件字段时使用相同结构，例如 data.file="required"。

开放 API 接口参考 ​

1. 服务地址与鉴权 ​

2. 接口总览 ​

3. 通用约定 ​

3.1 通用响应结构 ​

3.2 标识符 ​

3.3 文件和批次状态 ​

3.4 模板字段结构 ​

3.5 调用与字段命名 ​

3.6 可选参数的实际行为 ​

4. 开放 API ​

4.1 概述 ​

4.1.1 单接口说明格式 ​

4.2 文件管理 ​

4.2.1 上传文件 ​

metadata 与 user_email 的行为 ​

4.2.2 删除文件 ​

4.2.3 修改文件模板类别 ​

4.3 任务管理 ​

4.3.1 查询批次任务列表 ​

4.3.2 重新启动任务 ​

4.3.3 取消任务 ​

4.4 模板与文件处理 ​

4.4.1 获取模板列表 ​

4.4.2 获取模板字段列表 ​

4.4.3 创建模板 ​

4.4.4 更新模板 ​

4.4.5 删除模板 ​

4.4.6 上传或更改模板样本 ​

4.4.7 自定义字段抽取 ​

4.4.8 获取文件处理结果 ​

4.4.9 更新文件处理结果 ​

4.4.10 获取文件分类 ​

4.5 提醒规则管理 ​

4.5.1 鉴权与组织隔离 ​

4.5.2 请求模型 ​

4.5.3 接口与响应 ​

4.5.4 错误与业务复用 ​

4.6 资产管理 ​

4.6.1 获取资产信息 ​

5. 全接口请求参数字段索引 ​

6. 推荐调用流程与错误处理 ​

开放 API 接口参考

1. 服务地址与鉴权

2. 接口总览

3. 通用约定

3.1 通用响应结构

3.2 标识符

3.3 文件和批次状态

3.4 模板字段结构

3.5 调用与字段命名

3.6 可选参数的实际行为

4. 开放 API

4.1 概述

4.1.1 单接口说明格式

4.2 文件管理

4.2.1 上传文件

metadata 与 user_email 的行为

4.2.2 删除文件

4.2.3 修改文件模板类别

4.3 任务管理

4.3.1 查询批次任务列表

4.3.2 重新启动任务

4.3.3 取消任务

4.4 模板与文件处理

4.4.1 获取模板列表

4.4.2 获取模板字段列表

4.4.3 创建模板

4.4.4 更新模板

4.4.5 删除模板

4.4.6 上传或更改模板样本

4.4.7 自定义字段抽取

4.4.8 获取文件处理结果

4.4.9 更新文件处理结果

4.4.10 获取文件分类

4.5 提醒规则管理

4.5.1 鉴权与组织隔离

4.5.2 请求模型

4.5.3 接口与响应

4.5.4 错误与业务复用

4.6 资产管理

4.6.1 获取资产信息

5. 全接口请求参数字段索引

6. 推荐调用流程与错误处理