开放平台接入说明

说明如何完成开放平台固定审查能力与智慧评审能力的接入与联调。

这项能力适合什么场景

如果你希望在另一个产品里直接调用 BidRisk 的能力，而不是让用户手动进入主平台操作，那么当前开放平台就是最合适的接入方式。

当前公开能力分为两类：

固定审查能力
tender_review.v1
contract_review.v1
智慧评审能力
smart-evaluation/rules
smart-evaluation/bidders
smart-evaluation/qualification
smart-evaluation/business
smart-evaluation/technical
法律法规库能力
GET /platform/v1/regulations
GET /platform/v1/regulations/{regulation_id}

两类能力共享同一个 workspace 容器，但公开路径不同：

固定审查：workspace + review/{slug} + polling
智慧评审：workspace + smart-evaluation 子路径 + 阶段轮询

接入前需要准备什么

在开始联调前，需要先完成应用开通并获取接入凭证。

通常包括：

开通应用接入
获取 API Key 当前凭证发放不通过开放接口完成。

第一步：创建 Workspace

workspace 是开放平台的资料容器。

请求示例：

curl -X POST "http://localhost:8000/platform/v1/workspaces" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{
    "external_ref": "erp-project-001",
    "title": "XX 项目审查"
  }'

调用成功后会返回一个 workspace_id，后续上传、状态轮询和能力执行都围绕这个 workspace 进行。

第二步：上传文件

平台提供两种上传方式。

方式一：TUS 断点续传

适合大型 PDF 或网络不稳定的环境。

先获取当前工作区的上传配置：

curl -X POST "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/upload-config" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

平台会返回：upload_url、upload_token、project_id、user_id。

上传示例（使用 tus-js-client）：

const upload = new tus.Upload(file, {
  endpoint: uploadConfig.upload_url,
  headers: { "Upload-Token": uploadConfig.upload_token },
  metadata: {
    filename: file.name,
    project_id: String(uploadConfig.project_id),
    user_id: String(uploadConfig.user_id),
    upload_token: uploadConfig.upload_token,
  },
});
upload.start();

方式二：标准 Multipart 上传

适合常规大小文件或无法使用 TUS 客户端的场景。

curl -X POST "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/files" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -F "file=@/path/to/your/file.pdf"

成功返回：

{
  "id": 123,
  "filename": "file.pdf",
  "parse_status": "pending",
  "file_size": 1048576
}

第三步：等待资料就绪

文件上传完成后，不代表可以立刻发起审查。还需要等待平台完成解析与准备状态检查。

轮询接口：

curl "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/status" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

建议至少满足以下条件后再继续：

is_prepare_ready = true
已有至少一个 parse_status = parsed 的文件
若需要固定招标审查，已识别出招标文件，或 recommended_tender_file_id 不为空
若需要固定合同审查，至少已有一个 doc_stage = contract 的已解析文件

固定审查能力接入

固定审查能力的推荐入口是 workspace/review/{slug}。

发起固定审查

curl -X POST "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/review/tender" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{
    "force_rerun": false
  }'

说明：

当前固定审查类型支持 tender 与 contract
force_rerun = false 且存在未结束中的同类审查时，会直接返回当前运行中的结果
返回的 run_id 仍可作为兼容查询标识使用

查询固定审查状态

curl "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/review/tender" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

开放平台当前使用以下状态：

queued
running
succeeded
failed

拉取固定审查结果

curl "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/review/tender/result" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

成功时会返回四类核心信息：

summary
dimensions
findings
evidences

如果 run 还没结束，会返回：

error_code = run_not_completed

兼容旧版 `/runs`

旧版 /platform/v1/runs 仍保留给已上线接入方：

POST /platform/v1/runs
GET /platform/v1/runs/{run_id}
GET /platform/v1/runs/{run_id}/result

兼容口径：

仅继续支持 tender_review.v1 与 contract_review.v1
新接入统一使用 workspace/{workspace_id}/review/{slug}
历史请求中的 callback_url 字段仍可传入，但平台会忽略，不再触发 webhook

智慧评审能力接入

智慧评审当前不走 /runs，而是使用 workspace 下的显式场景子路径。

推荐流程如下：

创建 workspace
上传所有招标文件、投标文件
外部系统整包提交 rules
外部系统整包提交 bidders 与 file_ids 绑定
按需发起 qualification、business、technical
轮询对应阶段结果

法律法规库只读接口

法规库能力独立于 workspace，适用于法规名称搜索与正文详情读取。

查询法规列表

curl "http://localhost:8000/platform/v1/regulations?q=招标投标法&page=1&page_size=20" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

支持参数：

q
document_type
page
page_size

说明：

当前仅开放平台法规
当前搜索只匹配法规标题、文号、发文机关

读取法规详情

curl "http://localhost:8000/platform/v1/regulations/${REGULATION_ID}" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

提交规则

接口：

PUT /platform/v1/workspaces/{workspace_id}/smart-evaluation/rules
GET /platform/v1/workspaces/{workspace_id}/smart-evaluation/rules

请求示例：

curl -X PUT "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/smart-evaluation/rules" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{
    "qualification_items": [
      {
        "rule_id": "q_001",
        "name": "营业执照",
        "is_critical": true,
        "description": "投标人须具备有效营业执照"
      }
    ],
    "business_criteria": [
      {
        "rule_id": "b_001",
        "name": "类似业绩",
        "max_score": 10,
        "description": "每提供 1 个业绩得 2 分，最高 10 分"
      }
    ],
    "technical_criteria": [
      {
        "rule_id": "t_001",
        "name": "施工组织方案",
        "max_score": 20,
        "description": "根据完整性、可行性评分"
      }
    ]
  }'

说明：

当前使用 PUT 做整包覆盖，而不是局部 patch
如果应用侧本来就有自己的规则配置，建议始终由应用侧维护完整规则源

提交投标人及文件绑定

接口：

PUT /platform/v1/workspaces/{workspace_id}/smart-evaluation/bidders
GET /platform/v1/workspaces/{workspace_id}/smart-evaluation/bidders

请求示例：

curl -X PUT "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/smart-evaluation/bidders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{
    "bidders": [
      {
        "bidder_ref": "erp-bidder-001",
        "name": "某建设有限公司",
        "bid_price": 5000000,
        "file_ids": [101, 102]
      },
      {
        "bidder_ref": "erp-bidder-002",
        "name": "某工程有限公司",
        "bid_price": 5200000,
        "file_ids": [103]
      }
    ]
  }'

说明：

bidders 由外部系统提交
建议在所有文件上传完成后，再统一调用该接口覆盖一次当前投标人集合
file_ids 必须属于当前 workspace
bidder_ref 在当前请求体内必须唯一

可选：触发招标文件解析

接口：

POST /platform/v1/workspaces/{workspace_id}/tender_parse
GET /platform/v1/workspaces/{workspace_id}/tender_parse

请求示例：

curl -X POST "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/tender_parse" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{
    "file_id": 101
  }'

说明：

tender_parse 是独立的招标文件解析能力，不仅用于智慧评审
这是可选能力，不是智慧评审主链路前提
如果不传 file_id，平台会尝试自动识别推荐招标文件

发起评审阶段

接口：

POST /platform/v1/workspaces/{workspace_id}/smart-evaluation/qualification
GET /platform/v1/workspaces/{workspace_id}/smart-evaluation/qualification
POST /platform/v1/workspaces/{workspace_id}/smart-evaluation/business
GET /platform/v1/workspaces/{workspace_id}/smart-evaluation/business
POST /platform/v1/workspaces/{workspace_id}/smart-evaluation/technical
GET /platform/v1/workspaces/{workspace_id}/smart-evaluation/technical

发起阶段请求示例：

curl -X POST "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/smart-evaluation/business" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${BIDRISK_API_KEY}" \
  -d '{}'

如果需要强制重跑，可传：

{
  "force_rerun": true
}

查询结果示例：

curl "http://localhost:8000/platform/v1/workspaces/${WORKSPACE_ID}/smart-evaluation/business" \
  -H "X-API-Key: ${BIDRISK_API_KEY}"

返回示例：

{
  "status": "succeeded",
  "summary": {
    "total_bidders": 2,
    "completed": 2,
    "failed": 0
  },
  "results": [
    {
      "bidder_ref": "erp-bidder-001",
      "name": "某建设有限公司",
      "result": {
        "b_001": 8.5,
        "score": 8.5
      }
    }
  ]
}

阶段状态枚举：

not_started
queued
running
succeeded
failed

常见阻断原因

固定审查常见阻断值包括：

no_files
files_processing
no_parsed_files
missing_tender_file
missing_contract_file

智慧评审常见阻断值包括：

missing_bidders
missing_bidder_files
missing_stage_rules
invalid_bidder_files
missing_tender_file

这些错误通常意味着：

文件还没上传完整
文件刚上传完，还在解析
规则还没提交
投标人还没提交
投标人和文件绑定关系不完整

当前边界

当前阶段边界如下：

固定审查仅支持 tender_review.v1 与 contract_review.v1
智慧评审当前仅对外开放 rules、bidders、qualification、business、technical
智慧评审当前不对外开放价格评分与报告生成
不支持公开发放 API Key
固定审查与智慧评审当前都以轮询为主

建议的接入顺序

如果你准备做一次最小联调，建议按下面顺序：

完成应用开通并获取 API Key
创建一个 workspace
上传所有关联文件
轮询 workspace/status 直到资料基本就绪
如果接固定审查，创建 tender_review.v1 或 contract_review.v1 run
如果接智慧评审，依次提交 rules 和 bidders
发起 qualification、business 或 technical
轮询对应阶段结果

开放平台接入说明

这项能力适合什么场景

接入前需要准备什么

第一步：创建 Workspace

第二步：上传文件

方式一：TUS 断点续传

方式二：标准 Multipart 上传

第三步：等待资料就绪

固定审查能力接入

发起固定审查

查询固定审查状态

拉取固定审查结果

兼容旧版 /runs

智慧评审能力接入

法律法规库只读接口

查询法规列表

读取法规详情

提交规则

提交投标人及文件绑定

可选：触发招标文件解析

发起评审阶段

常见阻断原因

当前边界

建议的接入顺序

兼容旧版 `/runs`