API V1 · 完整接入指南

从注册审核,到下载结果

覆盖账号申请、API Key、四项业务能力、异步任务、文件下载和管理员接口。第一次接入建议先在开发者控制台完成在线调试。

01 · 先看懂整体流程

这是异步接口,不是提交后立即返回最终结果

四项业务能力都采用异步任务。第一次请求只负责上传文件并创建任务,返回 id(任务编号);你的程序再根据任务编号查询进度,成功后获取 JSON 和生成文件。

1提交文件返回 HTTP 202 和 id
→
2查询状态每 3~5 秒查询一次
→
3获取结果状态为 succeeded 后读取
→
4下载文件使用 files 中的下载地址
一句话记忆:提交接口拿任务编号,状态接口等任务完成,结果接口拿 JSON,文件接口下载生成文件。

02 · 接口总览

先按鉴权方式找到正确的接口

平台有三种访问方式。公开接口不需要凭据;控制台接口使用登录返回的 Bearer Token;业务任务接口使用 API Key。两种凭据不能互换。

公开无需凭据注册、登录、产品目录和健康检查
Bearer登录会话账号资料、API Key、用户审核和调试配置
API KeyX-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 不是一回事

登录账号

用于开发者控制台

自行注册并经管理员批准后使用,用来登录控制台、创建密钥和查看管理功能。不要把账号密码写进接口代码。

API Key

用于调用业务接口

格式以 sk_live_ 开头,通过请求头 X-API-Key 发送。完整密钥只显示一次。

所有业务请求都要携带这个请求头

HEADERX-API-Key: sk_live_你的密钥

控制台和管理接口使用登录会话

HEADERAuthorization: Bearer 登录返回的 token
不要泄露密钥:不要把 API Key 放进公开仓库、网页前端源码、截图、聊天记录或可被他人读取的日志。

每个账号只能查询和下载自己创建的任务。即使属于同一个租户,两个开发者账号之间也不能互相查看任务。

04 · 五分钟跑通

以合同审核为例完成一次调用

下面示例适用于 Windows PowerShell。部署到服务器后,把 http://127.0.0.1:8080 替换成正式域名。

第一步:准备地址和密钥

PowerShell
$BaseUrl = "http://127.0.0.1:8080"
$ApiKey = "sk_live_请替换为你的密钥"

第二步:上传文件并创建任务

PowerShell · curl.exe
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"
}

第三步:查询任务进度

PowerShell
$JobId = "job_abc123"
curl.exe "$BaseUrl/v1/jobs/$JobId" -H "X-API-Key: $ApiKey"

当 status 变成 succeeded 时再进入下一步;如果变成 failed,查看响应里的 error.code 和 error.message。

第四步:获取最终 JSON

PowerShell
curl.exe "$BaseUrl/v1/jobs/$JobId/result" -H "X-API-Key: $ApiKey"
查看完整 Python 自动轮询示例
Python · requests
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 秒调用一次状态接口,不要高频请求。

GET/v1/jobs/{job_id}
GET/v1/jobs查询当前账号最近 50 项任务
API 状态控制台中文是否继续轮询说明
queued排队中是任务等待 Worker 处理
submitting正在提交是正在交给内部业务系统
processing处理中是业务系统正在解析或调用 AI
succeeded已完成否可以读取结果和下载文件
failed失败否查看 error;文件未过期时可以重试
expired已过期否文件和结果已按保留规则清理

06 · 结果与文件

JSON 结果和生成文件要分别获取

GET/v1/jobs/{job_id}/result读取 JSON
GET/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"
      }
    ]
  }
}

下载生成文件

GET/v1/files/{file_id}
PowerShell
curl.exe -L "$BaseUrl/v1/files/file_xyz789" `
  -H "X-API-Key: $ApiKey" `
  -o "审核建议书.docx"
必须保留提示:所有 AI 输出均为“未经人工确认”。在把内容用于合同签署、生产操作或正式审批前,必须由有权限的人员复核。

07 · 失败任务

失败后如何重新处理

POST/v1/jobs/{job_id}/retry

只有状态为 failed、并且原上传文件仍在 7 天保留期内的任务可以重试。重试会创建新的任务编号,原失败任务不会被覆盖。

PowerShell
curl.exe -X POST "$BaseUrl/v1/jobs/$JobId/retry" `
  -H "X-API-Key: $ApiKey"
如果失败原因是 SOP_AI_FAILED 或请求超时,通常可以稍后重试;如果是文件格式错误,应先修正文件再重新上传。

08 · 产品接口

合同审核 API

上传一份 DOCX 合同,从指定立场生成结构化风险清单,并可生成带标注合同、修改完成合同和审核建议书。平台暂不开放依赖人工勾选步骤的 selected 模式。

POST/v1/contracts/review-jobsmultipart/form-data
字段必填默认值可选值与说明
file必填—真实 DOCX 文件,默认最大 30 MB
perspective否party_bparty_a 甲方;party_b 乙方
contract_type否processingprocessing 代工、purchase 采购、sales 销售、service 服务、lease 租赁
intensity否neutralneutral 中立;strong 强势
industry否companycompany 通用企业、food 食品、customer_service 客服外包
generation_mode否advice_onlyall 全部采纳并生成三份文件;high_required 仅采纳高风险和需补充项并生成三份文件;advice_only 不修改合同,仅返回建议书
output_format否docxdocx Word 文件;pdf PDF 文件

结果里重点看什么

risks风险清单,包括风险等级、原文、问题、建议和推荐文本
review_meta模型、失败批次和审核过程信息
review_options本次提交使用的审核视角和选项
generation_mode本次文件生成策略
output_format本次结果文件格式
files按生成方式返回标注版、修改版和/或审核建议书,kind 用于区分文件类型

09 · 产品接口

作业指导书整理 API

上传 DOCX 或 PDF,返回标准化 SOP、质量指标、待确认问题和可选看板结构。

POST/v1/sop/jobsmultipart/form-data
字段必填默认值说明
file必填—DOCX 或 PDF,默认最大 30 MB
include_board否true是否同时返回现场看板结构
PowerShell
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 模板,成功后通常返回一份汇总工作簿。

POST/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是否由经营数据系统保存为新版本
PowerShell · curl.exe
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_summary
download_warning汇总已完成但结果工作簿下载失败时出现
三个上传字段分别执行文件大小检查。订单表和推广表必填,模板不需要时请直接省略 summary_template_file。

11 · 产品接口

周报月报 AI 分析 API

上传部门周报或月报,指定统计区间后生成结构化分析结果,并保存一份可下载的 HTML 分析页。

POST/v1/reports/analysis-jobsmultipart/form-data
字段必填默认值说明
file必填—支持 DOCX、XLSX、PDF、TXT,默认最大 30 MB
department必填—部门名称,不能只包含空格
start_date必填—开始日期,格式 YYYY-MM-DD
end_date必填—结束日期,且不能早于开始日期
report_type否weeklyweekly 周报;monthly 月报
PowerShell · curl.exe
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 或 monthly
department本次报告所属部门
start_date / end_date本次分析统计区间
filesHTML 分析结果;kind 为 report_ai_result

12 · 账号与密钥接口

注册、登录和 API Key 生命周期

注册与登录请求使用 JSON。登录成功后获得 Bearer Token,再用它创建 API Key;业务系统调用时只发送 API Key,不发送用户名和密码。

1. 提交注册申请

POST/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. 登录并保存会话

POST/v1/auth/login公开 · application/json
PowerShell
$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 或 admin

3. 创建 API Key

POST/v1/api-keysBearer Token
PowerShell
$KeyResult = Invoke-RestMethod -Method Post `
  -Uri "$BaseUrl/v1/api-keys" `
  -Headers $SessionHeaders `
  -ContentType "application/json" `
  -Body '{"name":"生产服务端"}'

$ApiKey = $KeyResult.api_key
api_key 只返回一次:服务端以后只返回名称、前缀和使用状态。若未保存完整值,应停用旧密钥并重新创建。

4. 查看、停用与删除密钥记录

GET/v1/api-keys列出自己的密钥
DELETE/v1/api-keys/{key_id}停用密钥,立即拒绝后续调用
DELETE/v1/api-keys/{key_id}/record仅可永久删除已停用记录

其他账号接口

GET/v1/me查询当前用户与租户编号
POST/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 后应通过安全渠道交给用户,并要求其登录后立即修改。

在线调试接口登记

GET/v1/admin/debug-interface-catalog查看平台内置能力与登记状态
GET/v1/admin/debug-interfaces包括已停用登记
POST/v1/admin/debug-interfaces登记平台内置能力
PATCH/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。

同步 HTTP 错误结构
{
  "detail": "统计日期格式必须是 YYYY-MM-DD"
}

常见 HTTP 状态码

状态码含义处理方式
400参数或文件格式不正确根据 detail 修改请求
401缺少、无效或已停用的访问凭据按接口类型检查 Authorization 或 X-API-Key
403账号未获批准、已停用或权限不足等待审核,或联系管理员检查角色与状态
404任务或文件不存在确认任务属于当前账号且编号正确
409当前状态不允许操作等待任务完成,或只重试 failed 任务
410原文件已过期重新上传文件
413文件超过大小限制压缩或拆分文件
422JSON、表单字段或枚举值未通过校验对照字段名称、类型、必填项和可选值
503就绪检查发现依赖服务不可用查看 /health/ready 的组件状态

常见任务错误码

错误码含义建议
SOP_AI_FAILED作业指导书 AI 调用失败或超时稍后点击重新处理
SOP_SERVICE_NOT_CONFIGUREDSOP 服务账号未配置联系管理员完成部署配置
SOP_LOGIN_FAILED平台无法登录内部 SOP 服务联系管理员检查服务账号
SOP_SERVICE_UNAVAILABLESOP 服务不可访问联系管理员检查业务服务
SOP_SERVICE_REJECTEDSOP 服务拒绝请求检查文件内容,或联系管理员查看服务响应
SOP_TASK_MISSINGSOP 服务未返回任务编号保留平台任务编号并联系管理员
SOP_PROCESSING_FAILEDSOP 后台处理失败查看 message 后修正文件或重试
SOP_PROCESSING_TIMEOUTSOP 任务超过平台等待时间确认业务系统状态后重试
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 天

上传文件到期后删除
生成文件到期后删除
结果 JSON到期后清理
任务审计状态保留任务编号和必要状态

每条任务响应中的 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 忘记保存了怎么办?

控制台会保留密钥名称、前缀、创建时间、最近使用时间和停用状态,但完整密钥不能再次查看。请停用旧密钥并创建一个新密钥;已停用的记录可以永久删除。

还不确定请求是否正确?

先在开发者控制台用同一个文件跑通,再把成功请求迁移到自己的程序。技术人员也可以使用 OpenAPI 页面查看原始请求结构。