01 · 先看懂整体流程
这是异步接口,不是提交后立即返回最终结果
四项业务能力都采用异步任务。第一次请求只负责上传文件并创建任务,返回 id(任务编号);你的程序再根据任务编号查询进度,成功后获取 JSON 和生成文件。
02 · 接口总览
先按鉴权方式找到正确的接口
平台有三种访问方式。公开接口不需要凭据;控制台接口使用登录返回的 Bearer Token;业务任务接口使用 API Key。两种凭据不能互换。
公开接口
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /health、/health/live、/health/ready | 平台、存活和就绪状态 |
| GET | /v1/products | 查询已接入产品和支持格式 |
| POST | /v1/auth/register | 提交开发者注册申请 |
| POST | /v1/auth/login | 登录并取得 Bearer Token |
开发者与管理员接口(Bearer Token)
| 方法 | 路径 | 权限与用途 |
|---|---|---|
| GET | /v1/me、/v1/system/status | 已登录用户资料和运行状态 |
| POST | /v1/me/password | 修改自己的登录密码 |
| GET POST DELETE | /v1/api-keys | 创建、查看、停用和删除自己的密钥 |
| GET | /v1/debug-interfaces | 查询当前账号可用的在线调试能力 |
| ADMIN | /v1/admin/users/* | 审核、停用、重置密码和删除用户 |
| ADMIN | /v1/admin/debug-interface* | 查看和管理在线调试接口登记 |
业务任务接口(API Key)
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /v1/contracts/review-jobs | 创建合同审核任务 |
| POST | /v1/sop/jobs | 创建作业指导书整理任务 |
| POST | /v1/ecommerce/summary-jobs | 创建电商经营数据汇总任务 |
| POST | /v1/reports/analysis-jobs | 创建周报或月报分析任务 |
| GET | /v1/jobs、/v1/jobs/{job_id} | 查询自己的任务列表和单项进度 |
| POST | /v1/jobs/{job_id}/retry | 重试仍在保留期内的失败任务 |
| GET | /v1/jobs/{job_id}/result、/result.json | 读取或下载成功任务的 JSON 结果 |
| GET | /v1/files/{file_id} | 下载任务生成文件 |
03 · 身份认证
登录账号和 API Key 不是一回事
用于开发者控制台
自行注册并经管理员批准后使用,用来登录控制台、创建密钥和查看管理功能。不要把账号密码写进接口代码。
用于调用业务接口
格式以 sk_live_ 开头,通过请求头 X-API-Key 发送。完整密钥只显示一次。
所有业务请求都要携带这个请求头
X-API-Key: sk_live_你的密钥控制台和管理接口使用登录会话
Authorization: Bearer 登录返回的 token每个账号只能查询和下载自己创建的任务。即使属于同一个租户,两个开发者账号之间也不能互相查看任务。
04 · 五分钟跑通
以合同审核为例完成一次调用
下面示例适用于 Windows PowerShell。部署到服务器后,把 http://127.0.0.1:8080 替换成正式域名。
第一步:准备地址和密钥
$BaseUrl = "http://127.0.0.1:8080"
$ApiKey = "sk_live_请替换为你的密钥"第二步:上传文件并创建任务
curl.exe -X POST "$BaseUrl/v1/contracts/review-jobs" `
-H "X-API-Key: $ApiKey" `
-F "file=@C:\测试文件\采购合同.docx" `
-F "perspective=party_b" `
-F "contract_type=purchase" `
-F "intensity=neutral" `
-F "industry=company" `
-F "generation_mode=all" `
-F "output_format=docx"成功时返回 HTTP 202 Accepted。请保存返回的 id,它就是任务编号。
{
"id": "job_abc123",
"product_code": "contract-review",
"job_type": "contract_review",
"status": "queued",
"progress": 0,
"message": "任务已进入队列",
"original_filename": "采购合同.docx",
"options": {
"perspective": "party_b",
"contract_type": "purchase",
"intensity": "neutral",
"industry": "company",
"generation_mode": "all",
"output_format": "docx"
},
"confirmation_status": "unconfirmed",
"notice": "本结果由 AI 生成,未经人工确认,仅供辅助参考。",
"error": null,
"created_at": "2026-10-15T06:30:00",
"updated_at": "2026-10-15T06:30:00",
"expires_at": "2026-10-22T06:30:00",
"status_url": "/v1/jobs/job_abc123",
"result_url": "/v1/jobs/job_abc123/result"
}第三步:查询任务进度
$JobId = "job_abc123"
curl.exe "$BaseUrl/v1/jobs/$JobId" -H "X-API-Key: $ApiKey"当 status 变成 succeeded 时再进入下一步;如果变成 failed,查看响应里的 error.code 和 error.message。
第四步:获取最终 JSON
curl.exe "$BaseUrl/v1/jobs/$JobId/result" -H "X-API-Key: $ApiKey"查看完整 Python 自动轮询示例
import time
import requests
BASE_URL = "http://127.0.0.1:8080"
API_KEY = "sk_live_请替换为你的密钥"
HEADERS = {"X-API-Key": API_KEY}
with open(r"C:\测试文件\采购合同.docx", "rb") as file:
response = requests.post(
f"{BASE_URL}/v1/contracts/review-jobs",
headers=HEADERS,
files={"file": ("采购合同.docx", file)},
data={
"perspective": "party_b",
"contract_type": "purchase",
"intensity": "neutral",
"industry": "company",
"generation_mode": "all",
"output_format": "docx",
},
timeout=60,
)
response.raise_for_status()
job = response.json()
while True:
status_response = requests.get(
BASE_URL + job["status_url"], headers=HEADERS, timeout=30
)
status_response.raise_for_status()
status = status_response.json()
print(status["status"], status["progress"], status["message"])
if status["status"] == "succeeded":
break
if status["status"] in {"failed", "expired"}:
raise RuntimeError(status.get("error") or status["message"])
time.sleep(5)
result_response = requests.get(
BASE_URL + job["result_url"], headers=HEADERS, timeout=30
)
result_response.raise_for_status()
print(result_response.json())05 · 通用任务接口
如何判断任务是否完成
开发者控制台会每 5 秒自动刷新。你自己的程序建议每 3~5 秒调用一次状态接口,不要高频请求。
/v1/jobs/{job_id}/v1/jobs查询当前账号最近 50 项任务| API 状态 | 控制台中文 | 是否继续轮询 | 说明 |
|---|---|---|---|
queued | 排队中 | 是 | 任务等待 Worker 处理 |
submitting | 正在提交 | 是 | 正在交给内部业务系统 |
processing | 处理中 | 是 | 业务系统正在解析或调用 AI |
succeeded | 已完成 | 否 | 可以读取结果和下载文件 |
failed | 失败 | 否 | 查看 error;文件未过期时可以重试 |
expired | 已过期 | 否 | 文件和结果已按保留规则清理 |
06 · 结果与文件
JSON 结果和生成文件要分别获取
/v1/jobs/{job_id}/result读取 JSON/v1/jobs/{job_id}/result.json下载 JSON 文件结果中的 files 是可下载文件列表。如果列表为空,表示本次只生成了 JSON,或文件生成阶段出现了警告。
{
"job_id": "job_abc123",
"status": "succeeded",
"confirmation_status": "unconfirmed",
"notice": "本结果由 AI 生成,未经人工确认,仅供辅助参考。",
"result": {
"product": "contract-review",
"risks": [],
"generation_mode": "all",
"output_format": "docx",
"files": [
{
"file_id": "file_annotated",
"kind": "contract_annotated",
"file_name": "合同_带标注合同_未经人工确认.docx",
"download_url": "/v1/files/file_annotated",
"expires_at": "2026-10-22T06:30:00"
},
{
"file_id": "file_modified",
"kind": "contract_modified",
"file_name": "合同_修改完成合同_未经人工确认.docx",
"download_url": "/v1/files/file_modified",
"expires_at": "2026-10-22T06:30:00"
},
{
"file_id": "file_advice",
"kind": "contract_advice",
"file_name": "合同_AI审核建议书_未经人工确认.docx",
"download_url": "/v1/files/file_advice",
"expires_at": "2026-10-22T06:30:00"
}
]
}
}下载生成文件
/v1/files/{file_id}curl.exe -L "$BaseUrl/v1/files/file_xyz789" `
-H "X-API-Key: $ApiKey" `
-o "审核建议书.docx"07 · 失败任务
失败后如何重新处理
/v1/jobs/{job_id}/retry只有状态为 failed、并且原上传文件仍在 7 天保留期内的任务可以重试。重试会创建新的任务编号,原失败任务不会被覆盖。
curl.exe -X POST "$BaseUrl/v1/jobs/$JobId/retry" `
-H "X-API-Key: $ApiKey"SOP_AI_FAILED 或请求超时,通常可以稍后重试;如果是文件格式错误,应先修正文件再重新上传。08 · 产品接口
合同审核 API
上传一份 DOCX 合同,从指定立场生成结构化风险清单,并可生成带标注合同、修改完成合同和审核建议书。平台暂不开放依赖人工勾选步骤的 selected 模式。
/v1/contracts/review-jobsmultipart/form-data| 字段 | 必填 | 默认值 | 可选值与说明 |
|---|---|---|---|
file | 必填 | — | 真实 DOCX 文件,默认最大 30 MB |
perspective | 否 | party_b | party_a 甲方;party_b 乙方 |
contract_type | 否 | processing | processing 代工、purchase 采购、sales 销售、service 服务、lease 租赁 |
intensity | 否 | neutral | neutral 中立;strong 强势 |
industry | 否 | company | company 通用企业、food 食品、customer_service 客服外包 |
generation_mode | 否 | advice_only | all 全部采纳并生成三份文件;high_required 仅采纳高风险和需补充项并生成三份文件;advice_only 不修改合同,仅返回建议书 |
output_format | 否 | docx | docx Word 文件;pdf PDF 文件 |
结果里重点看什么
risks风险清单,包括风险等级、原文、问题、建议和推荐文本review_meta模型、失败批次和审核过程信息review_options本次提交使用的审核视角和选项generation_mode本次文件生成策略output_format本次结果文件格式files按生成方式返回标注版、修改版和/或审核建议书,kind 用于区分文件类型09 · 产品接口
作业指导书整理 API
上传 DOCX 或 PDF,返回标准化 SOP、质量指标、待确认问题和可选看板结构。
/v1/sop/jobsmultipart/form-data| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
file | 必填 | — | DOCX 或 PDF,默认最大 30 MB |
include_board | 否 | true | 是否同时返回现场看板结构 |
curl.exe -X POST "$BaseUrl/v1/sop/jobs" `
-H "X-API-Key: $ApiKey" `
-F "file=@C:\测试文件\原始作业指导书.docx" `
-F "include_board=true"结果里重点看什么
sop标准化后的作业指导书结构quality_metrics技术参数保留、丢失和新增内容等质量指标issues需要人工确认的问题列表parsing_warnings源文件解析警告board现场看板结构;关闭 include_board 时可能为空files整理稿等可下载文件files 为空时,请检查 document_generation_warning。这表示 SOP JSON 已生成,但 Word 文件生成或下载未完成。10 · 产品接口
电商经营数据汇总 API
同时上传订单表和推广表,按统计日期与店铺名称生成经营数据汇总。可选上传现有 XLSX 模板,成功后通常返回一份汇总工作簿。
/v1/ecommerce/summary-jobsmultipart/form-data| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
order_file | 必填 | — | 订单表;支持 CSV、XLS、XLSX |
promotion_file | 必填 | — | 推广表;支持 CSV、XLS、XLSX |
summary_template_file | 否 | 空 | 汇总模板,仅支持 XLSX |
report_date | 必填 | — | 统计日期,格式必须为 YYYY-MM-DD |
store_name | 否 | 默认店铺 | 店铺名称,不能只包含空格 |
operator_name | 否 | API平台 | 写入汇总记录的操作人 |
overwrite | 否 | false | 是否覆盖同日期、同店铺数据 |
save_as_new | 否 | false | 是否由经营数据系统保存为新版本 |
curl.exe -X POST "$BaseUrl/v1/ecommerce/summary-jobs" `
-H "X-API-Key: $ApiKey" `
-F "order_file=@C:\测试文件\订单表.xlsx" `
-F "promotion_file=@C:\测试文件\推广表.xlsx" `
-F "summary_template_file=@C:\测试文件\经营汇总模板.xlsx" `
-F "report_date=2026-10-15" `
-F "store_name=旗舰店" `
-F "operator_name=张三" `
-F "overwrite=false" `
-F "save_as_new=false"结果里重点看什么
summary经营数据系统返回的原始汇总信息,包括成功标记和任务编号等report_date本次统计日期store_name本次处理的店铺名称files生成的经营数据汇总 XLSX;kind 为 ecommerce_summarydownload_warning汇总已完成但结果工作簿下载失败时出现summary_template_file。11 · 产品接口
周报月报 AI 分析 API
上传部门周报或月报,指定统计区间后生成结构化分析结果,并保存一份可下载的 HTML 分析页。
/v1/reports/analysis-jobsmultipart/form-data| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
file | 必填 | — | 支持 DOCX、XLSX、PDF、TXT,默认最大 30 MB |
department | 必填 | — | 部门名称,不能只包含空格 |
start_date | 必填 | — | 开始日期,格式 YYYY-MM-DD |
end_date | 必填 | — | 结束日期,且不能早于开始日期 |
report_type | 否 | weekly | weekly 周报;monthly 月报 |
curl.exe -X POST "$BaseUrl/v1/reports/analysis-jobs" `
-H "X-API-Key: $ApiKey" `
-F "file=@C:\测试文件\运营部周报.docx" `
-F "department=运营部" `
-F "start_date=2026-10-08" `
-F "end_date=2026-10-14" `
-F "report_type=weekly"结果里重点看什么
remote_report_id内部报告系统生成的报告编号remote_report_path内部报告记录路径,仅用于审计定位,不应作为公开下载地址report_type本次分析类型:weekly 或 monthlydepartment本次报告所属部门start_date / end_date本次分析统计区间filesHTML 分析结果;kind 为 report_ai_result12 · 账号与密钥接口
注册、登录和 API Key 生命周期
注册与登录请求使用 JSON。登录成功后获得 Bearer Token,再用它创建 API Key;业务系统调用时只发送 API Key,不发送用户名和密码。
1. 提交注册申请
/v1/auth/register公开 · application/json{
"username": "developer01",
"password": "至少8位的登录密码"
}用户名长度 2~80,密码长度 8~160。成功返回 HTTP 201 Created,状态固定为 pending;管理员批准前登录会返回 403。
{
"id": 12,
"username": "developer01",
"status": "pending",
"message": "注册申请已提交,请等待管理员审核。审核通过后即可登录。"
}2. 登录并保存会话
/v1/auth/login公开 · application/json$Login = Invoke-RestMethod -Method Post `
-Uri "$BaseUrl/v1/auth/login" `
-ContentType "application/json" `
-Body '{"username":"developer01","password":"你的登录密码"}'
$Token = $Login.token
$SessionHeaders = @{ Authorization = "Bearer $Token" }tokenBearer Token;后续控制台接口放入 Authorization 请求头expires_at当前登录会话到期时间user.id用户编号user.roledeveloper 或 admin3. 创建 API Key
/v1/api-keysBearer Token$KeyResult = Invoke-RestMethod -Method Post `
-Uri "$BaseUrl/v1/api-keys" `
-Headers $SessionHeaders `
-ContentType "application/json" `
-Body '{"name":"生产服务端"}'
$ApiKey = $KeyResult.api_keyapi_key 只返回一次:服务端以后只返回名称、前缀和使用状态。若未保存完整值,应停用旧密钥并重新创建。4. 查看、停用与删除密钥记录
/v1/api-keys列出自己的密钥/v1/api-keys/{key_id}停用密钥,立即拒绝后续调用/v1/api-keys/{key_id}/record仅可永久删除已停用记录其他账号接口
/v1/me查询当前用户与租户编号/v1/me/password修改密码并撤销全部旧登录会话{
"current_password": "当前登录密码",
"new_password": "新的至少8位密码"
}修改密码成功返回 {"password_changed": true, "sessions_revoked": true}。现有 API Key 不受影响。
13 · 管理员接口
用户审核与在线调试能力管理
以下接口都要求管理员 Bearer Token。普通开发者调用会返回 403。用户状态包括 pending、rejected、active 和 disabled。
用户管理
| 方法 | 路径 | 规则 |
|---|---|---|
| GET | /v1/admin/users | 列出本租户的注册与账号记录 |
| POST | /v1/admin/users/{user_id}/approve | 仅可批准 pending 用户 |
| POST | /v1/admin/users/{user_id}/reject | 仅可拒绝 pending 用户 |
| POST | /v1/admin/users/{user_id}/disable | 停用已批准用户,并撤销其会话和 API Key |
| POST | /v1/admin/users/{user_id}/reset-password | 为已批准且启用的用户生成一次性临时密码 |
| DELETE | /v1/admin/users/{user_id} | 仅可删除已拒绝或已停用用户;历史任务审计保留 |
reset-password 返回 temporary_password 后应通过安全渠道交给用户,并要求其登录后立即修改。在线调试接口登记
/v1/admin/debug-interface-catalog查看平台内置能力与登记状态/v1/admin/debug-interfaces包括已停用登记/v1/admin/debug-interfaces登记平台内置能力/v1/admin/debug-interfaces/{registration_id}修改名称、说明或启用状态{
"interface_code": "ecommerce-summary",
"display_name": "电商经营数据汇总",
"description": "供开发者在线调试经营数据汇总接口",
"is_enabled": true
}interface_code 只能选择平台已经接入的能力,不能通过此接口配置任意外部 URL。普通用户通过 GET /v1/debug-interfaces 只能看到已启用项目。
14 · 错误处理
先判断 HTTP 错误,还是异步任务失败
查看 HTTP 状态码
例如密钥无效、格式不支持、文件太大。响应一般包含 detail。
查看任务 error
HTTP 202 已创建任务,但后台处理失败。查看 error.code 和 error.message。
{
"detail": "统计日期格式必须是 YYYY-MM-DD"
}常见 HTTP 状态码
| 状态码 | 含义 | 处理方式 |
|---|---|---|
400 | 参数或文件格式不正确 | 根据 detail 修改请求 |
401 | 缺少、无效或已停用的访问凭据 | 按接口类型检查 Authorization 或 X-API-Key |
403 | 账号未获批准、已停用或权限不足 | 等待审核,或联系管理员检查角色与状态 |
404 | 任务或文件不存在 | 确认任务属于当前账号且编号正确 |
409 | 当前状态不允许操作 | 等待任务完成,或只重试 failed 任务 |
410 | 原文件已过期 | 重新上传文件 |
413 | 文件超过大小限制 | 压缩或拆分文件 |
422 | JSON、表单字段或枚举值未通过校验 | 对照字段名称、类型、必填项和可选值 |
503 | 就绪检查发现依赖服务不可用 | 查看 /health/ready 的组件状态 |
常见任务错误码
| 错误码 | 含义 | 建议 |
|---|---|---|
SOP_AI_FAILED | 作业指导书 AI 调用失败或超时 | 稍后点击重新处理 |
SOP_SERVICE_NOT_CONFIGURED | SOP 服务账号未配置 | 联系管理员完成部署配置 |
SOP_LOGIN_FAILED | 平台无法登录内部 SOP 服务 | 联系管理员检查服务账号 |
SOP_SERVICE_UNAVAILABLE | SOP 服务不可访问 | 联系管理员检查业务服务 |
SOP_SERVICE_REJECTED | SOP 服务拒绝请求 | 检查文件内容,或联系管理员查看服务响应 |
SOP_TASK_MISSING | SOP 服务未返回任务编号 | 保留平台任务编号并联系管理员 |
SOP_PROCESSING_FAILED | SOP 后台处理失败 | 查看 message 后修正文件或重试 |
SOP_PROCESSING_TIMEOUT | SOP 任务超过平台等待时间 | 确认业务系统状态后重试 |
CONTRACT_SERVICE_REJECTED | 合同服务拒绝请求 | 检查合同文件,或联系管理员查看服务响应 |
CONTRACT_SERVICE_UNAVAILABLE | 合同服务不可访问 | 联系管理员检查业务服务 |
CONTRACT_REVIEW_FAILED | 合同审核任务失败 | 查看 message 后重新提交 |
CONTRACT_REVIEW_TIMEOUT | 合同审核超过平台等待时间 | 确认合同服务状态后重试 |
ECOMMERCE_SERVICE_REJECTED | 经营数据系统拒绝请求 | 检查表格内容、日期、店铺和覆盖选项 |
ECOMMERCE_SERVICE_UNAVAILABLE | 经营数据系统不可访问 | 联系管理员检查业务服务 |
ECOMMERCE_PACKAGE_INVALID | 平台内部经营数据文件包不完整 | 保留任务编号并联系管理员 |
ECOMMERCE_SUMMARY_FAILED | 经营数据汇总未成功完成 | 查看 message 中的业务系统说明 |
REPORT_AI_CREDENTIALS_MISSING | 报告系统服务账号未配置 | 联系管理员完成部署配置 |
REPORT_AI_LOGIN_FAILED | 报告系统服务账号登录失败 | 联系管理员检查服务账号 |
REPORT_AI_ANALYSIS_FAILED | 周报月报分析失败 | 检查文件内容后重试 |
REPORT_AI_SERVICE_UNAVAILABLE | 报告系统不可访问 | 联系管理员检查业务服务 |
REPORT_AI_RESPONSE_INVALID | 报告系统未返回有效报告编号 | 保留平台任务编号并联系管理员 |
REPORT_AI_RESULT_UNAVAILABLE | 报告已生成但结果页读取失败 | 确认报告系统状态后重试 |
WORKER_LEASE_EXPIRED | 处理任务的 Worker 心跳超时 | 确认 Worker 恢复后重试 |
INTERNAL_WORKER_ERROR | 平台任务进程发生未预期错误 | 保留任务编号并联系管理员 |
15 · 数据保留与安全
文件默认保留 7 天
每条任务响应中的 expires_at 是实际到期时间。需要长期留存时,请在到期前下载到你自己的受控存储。
- 正式环境必须使用 HTTPS。
- API Key 应保存在服务端环境变量或密钥管理系统中。
- 不要上传超出业务需要的个人信息或敏感信息。
- AI 结果必须经过人工复核,不能直接作为法律结论或生产指令。
16 · 常见问题
第一次接入最常遇到的问题
为什么提交接口没有直接返回审核结果?
因为业务处理是异步的。提交接口只创建任务,应根据 status_url 查询,成功后再调用 result_url。
在线调试和 Postman 有什么区别?
在线调试是针对本平台定制的简化工具;Postman 更适合开发人员自由构造请求和测试异常参数。两者调用的是同一套 API。
为什么管理员能看到任务,其他开发者账号看不到?
任务按创建账号隔离。必须使用创建该任务的账号所拥有的 API Key 查询。
任务成功了,为什么没有 Word 文件?
先检查结果中的 files 和 document_generation_warning。JSON 处理和 Word 生成是两个阶段,Word 阶段可能单独失败。
API Key 忘记保存了怎么办?
控制台会保留密钥名称、前缀、创建时间、最近使用时间和停用状态,但完整密钥不能再次查看。请停用旧密钥并创建一个新密钥;已停用的记录可以永久删除。
