OpenAPI 合同审查 V2 对接说明
OpenAPI 合同审查 V2 对接指南
面向 OpenAPI 调用方
版本：2026-09-30
路径前缀：/openapi/v2/audit
本文自包含：按本文即可完成「识别 → 选模板/立场 → 提交审查 → 查进度/结果 → 导出」全流程对接。
1. 快速开始
1.2 推荐对接路径
1) GET /openapi/v2/audit/template/list → 可选：拉模板树
2) POST /openapi/v2/audit/identification/document → 文档识别（落库返回 doc_id）
3) GET /openapi/v2/audit/{template_id}/points → 可选：勾选审查点
4) POST /openapi/v2/audit → JSON 提交审查（必传 doc_id），拿到 task_id
5) GET /openapi/v2/audit?task_id=... → 前端轮询进度 / 结果，直到 complete / error
6) GET /openapi/v2/audit/download → 导出带批注报告1.3 时序总览
2. 通用约定
2.1 鉴权（请求签名）
2.2 统一响应外壳
{
"code": 0,
"msg": "success",
"data": {}
}| code | 含义 |
|---|---|
0 | 成功 |
| 非 0 | 业务失败，看 msg |
2.3 任务状态
| status | 含义 | 调用方可做 |
|---|---|---|
pending | 审查中 | 继续轮询；可读 progress / message |
complete | 成功完成 | 拉详情 / 打开结果页 / 导出 |
error | 失败 | 读错误信息，可重试提交 |
对接方统一判断 status === "complete"表示成功终态。
3. 易错清单
| 错误做法 | 正确做法 |
|---|---|
提交不传文件也不传 doc_id | file / file_url / doc_id 至少一项 |
识别后只传 file_url 再传同一文件 | 优先传 doc_id，避免二次 ingest |
用 status === "completed" 判断完成 | 对外统一为 complete |
| 以为 POST 提交响应里就有 risks | 只有 task_id；结果看 GET / 回调 |
| 未完成就 download | 必须先 complete |
只传 doc_id 且缓存过期，导出缺文件 | 提交时同时带 file_url（识别返回的 url） |
callback_url 长时间不返回 | 尽快 2xx，业务异步落库 |
4. 附录：状态机
识别(同步)
│
▼
提交 POST /openapi/v2/audit
│
▼
pending ──(进度回调多次)──► pending(progress↑)
│
├──────────────────────► complete ──► 可详情 / 可导出
└──────────────────────► error修改于 2026-10-07 09:14:40