论文查重 / AIGC 检测接口

支持维普（大学生版/研究生版/编辑部版/职称版/作业版/科研版）、万方（本科版/硕博版/期刊版/职称版/新文献版/高职高专版/专著版/课程作业版）论文查重与维普/万方 AIGC 检测，出官方检测报告。报告不长期保留，完成后请及时下载保存。

• 查重产品按千字符计费，不足 1000 字符按 1000 字符计；维普职称版按万字符计费，不足 10000 字符按 10000 字符计
• AIGC 检测按篇计费，不论字数固定单价（万方文本AIGC检测除外，按千字符计费）
• 字符数以检测服务（维普/万方）返回的统计结果为准，平台不解析文档、不做本地统计与预估；统计完成后（通常在下单后一两分钟内）自动按实际字符数计费扣款，订单列表可见字符数与费用；检测失败的订单自动全额退回检测余额（退款后订单金额显示为 0）
• 使用独立的「检测余额」账户（与降重/降AI 字数账户互不相通）
• 订单为异步流程：提交后立即返回订单号，检测完成后通过回调通知获取结果
• 面向终端用户转售场景支持两段式下单：先拿到精确字数与费用，向用户收款后再确认扣费检测，见第 6 节

1. 接入信息

2. 产品清单

说明：查重与 AIGC 检测共用同一套接口，检测类型由提交订单时的 product_key 决定——传查重类产品（category=check）即查重，传 AIGC 类产品（category=aigc）即 AIGC 检测，无需其他类型参数；订单响应中的 category 字段标明该单类型。按千字符计费的产品不足 1000 字符按 1000 字符计；维普职称版不足 10000 字符按 10000 字符计；按篇计费的产品不论字数固定单价。单价与上架状态以产品列表接口实时返回为准，提交订单时按当时单价计费。

3. 产品列表

GET /api/v1/check/products
Authorization: Bearer YOUR_API_KEY

响应：

{
  "products": [
    {
      "product_key": "vip_dxs",
      "name": "维普大学生版",
      "platform": "vip",
      "category": "check",
      "billing_type": "per_1000_chars",
      "unit_price_yuan": 1.23,
      "max_chars": 500000,
      "description": null
    }
  ]
}

4. 余额查询

GET /api/v1/check/balance
Authorization: Bearer YOUR_API_KEY

响应：

{
  "balance_yuan": 200.0,
  "min_recharge_yuan": 1000.0,
  "recharge_fee_rate": 60
}

recharge_fee_rate 为充值手续费率（万分比，60 即 0.6%，仅控制台微信扫码充值收取，人工充值不收）。

5. 提交检测订单

POST /api/v1/check/orders
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

请求示例（curl）：

curl -X POST https://api.llmapi.fit/api/v1/check/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "product_key=vip_dxs" \
  -F "title=论文标题" \
  -F "author=张三" \
  -F "file=@paper.docx"

响应（同步完成校验、建单，字数统计与扣费异步进行）：

{
  "code": "success",
  "order_no": "CK20260930183000123456",
  "status": "pending",
  "billing_type": "per_1000_chars"
}

字符数与费用在字数统计完成后产生（通常一两分钟内），通过订单列表接口获取 char_count 与 fee_yuan；两段式订单此时推送 ORDER_COUNTED 回调并等待确认（见第 6 节）。字符数超过产品上限的订单会以失败结束（fail_reason 说明原因），不产生扣费。

常用错误码：insufficient_balance（检测余额为零，HTTP 402；两段式 auto_submit=false 不校验余额，扣费推迟到 confirm）、unsupported_file_type、file_too_large、missing_content（file 与 text 未二选一）、invalid_product（HTTP 404）、invalid_title / invalid_author、invalid_callback_url、storage_error（HTTP 500，可直接重试）。

6. 两段式下单：先出精确费用，确认后再检测

面向把检测转售给终端用户的场景：提交时传 auto_submit=false，流程变为两段——

sequenceDiagram
    autonumber
    participant C as 调用方
    participant P as 平台

    C->>P: POST /orders（auto_submit=false）
    Note right of P: 不校验余额、不扣费，仅保存送检文件并创建订单
    P-->>C: order_no, status=pending

    Note over P: 异步统计送检字符数（通常一两分钟）；<br/>字符数超产品上限则不推送，直接按失败结束（零扣费）
    P--)C: 推送 ORDER_COUNTED（charCount / feeYuan）
    Note over P: feeYuan 按下单时单价计算，confirm 实扣金额与之完全一致

    Note over C: 平台外动作：向终端用户按 feeYuan 精确收款

    C->>P: POST /orders/{order_no}/confirm
    alt 字数已就绪、余额足够
        P->>P: 扣检测余额（金额 = feeYuan）
        P-->>C: 200 status=checking，开始检测
    else 字数未就绪
        P-->>C: 409 word_count_not_ready（稍后重试）
    else 检测余额不足
        P-->>C: 402 insufficient_balance（订单保持待确认，充值后重试）
    else 重复调用（已确认/检测中/已完成）
        P-->>C: 200 幂等返回当前状态，不重复扣费
    else 已失败/已超时取消
        P-->>C: 409 order_cancelled
    end

    Note over P: 检测中，一般 2～10 分钟
    P--)C: ORDER_COMPLETED（含报告直链）/ ORDER_FAILED（失败已自动退款）

    opt 字数就绪起 24 小时内未 confirm
        P->>P: 自动取消（零扣费）
        P--)C: ORDER_FAILED（fail_reason：超时未确认，订单已取消）
    end

要点：

• feeYuan 按下单时的单价快照计算，与 confirm 时的实扣金额严格一致
• confirm 前平台零扣费、检测尚未开始；余额不足不会使订单失败，充值后重试 confirm 即可
• 字数就绪起默认 24 小时未 confirm 自动取消：零扣费，推 ORDER_FAILED（fail_reason 为「超时未确认，订单已取消」）；字数统计超时（建单后长时间无字数）同样零扣费结束
• 字数超过产品上限的两段式订单：不推送 ORDER_COUNTED，直接按失败结束（零扣费，走 ORDER_FAILED）
• ORDER_COUNTED 与终态通知推送到同一个回调地址（下单参数 callback_url 优先，其次账号级配置），验签、重试、幂等去重规则与检测结果通知完全一致（见第 9 节），按 orderNo + eventType 去重
• 不依赖回调也能推进：confirm 可直接重试——字数未就绪时返回 409 word_count_not_ready，就绪后重试即成功；也可用订单列表的 char_count > 0 判断字数已就绪

两段式下单示例：

curl -X POST https://api.llmapi.fit/api/v1/check/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "product_key=vip_dxs" \
  -F "title=论文标题" \
  -F "author=张三" \
  -F "file=@paper.docx" \
  -F "auto_submit=false"

ORDER_COUNTED 回调体（字数就绪时推送一次）：

{
  "eventType": "ORDER_COUNTED",
  "orderNo": "CK20260930183000123456",
  "productKey": "vip_dxs",
  "status": "submitted",
  "charCount": 12345,
  "feeYuan": 29.6,
  "countedAt": "2026-09-30T18:31:00.123456"
}

确认订单：

POST /api/v1/check/orders/CK20260930183000123456/confirm
Authorization: Bearer YOUR_API_KEY

curl -X POST https://api.llmapi.fit/api/v1/check/orders/CK20260930183000123456/confirm \
  -H "Authorization: Bearer YOUR_API_KEY"

另有一个防御性错误码：对 auto_submit=true 的单段式订单调用 confirm 返回 400 not_two_phase。confirm 开始检测后，检测失败的处理与单段式一致：全额退款 + ORDER_FAILED 通知。

7. 订单列表

统一状态机：pending（已建单）→ submitted（已受理，统计字数中）→ checking（检测中）→ completed / failed。检测一般 2～10 分钟完成，检测结果通过回调通知推送，请勿轮询；订单列表用于查看历史订单与费用对账。

两段式订单（第 6 节）的 submitted 包含「字数已统计、待确认」阶段：以 ORDER_COUNTED 回调到达、或列表中该订单 char_count > 0 识别；待确认订单 fee_yuan 显示应付金额（实扣为 0），confirm 后与实扣一致。

GET /api/v1/check/orders?page=1&page_size=10&status=checking
Authorization: Bearer YOUR_API_KEY

响应：

{
  "orders": [
    {
      "order_no": "CK20260930183000123456",
      "product_key": "vip_dxs",
      "product_name": "维普大学生版",
      "platform": "vip",
      "category": "check",
      "title": "论文标题",
      "status": "completed",
      "char_count": 12345,
      "fee_yuan": 29.6,
      "created_at": "2026-09-30 18:30:00",
      "completed_at": "2026-09-30 18:36:00",
      "has_report": true,
      "fail_reason": null
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

8. 回调地址设置

接收检测结果通知前，先设置回调地址。三种方式任选：

方式一：接口配置账号级默认地址（推荐，一次配置长期有效）

GET /api/v1/check/callback-url        # 查询当前配置
PUT /api/v1/check/callback-url        # 设置 / 修改 / 取消
Authorization: Bearer YOUR_API_KEY

设置（Content-Type: application/json）：

{ "callback_url": "https://your-server.com/check/callback" }

响应：

{ "code": "success", "callback_url": "https://your-server.com/check/callback" }

callback_url 传空字符串或 null 即取消通知（响应中 callback_url 为 null）。地址必须是 http/https 开头，≤512 字符。

方式二：提交订单时按单指定——提交订单接口的 callback_url 参数，仅对该单生效，优先于账号级配置。

方式三：控制台图形界面——控制台「回调设置」页直接填写保存，效果同方式一。

9. 结果回调通知

订单到达终态（completed / failed）时，平台向所配置的回调地址 POST 一次。两段式订单另有中途事件 ORDER_COUNTED（字数就绪推送，报文与规则见第 6 节），验签与重试机制与本节相同：

POST <您的回调地址>
Content-Type: application/json
X-Timestamp: 1789000000
X-Signature: <HMAC-SHA256(API_KEY, timestamp + "\n" + body) 的十六进制>

检测完成的通知体：

{
  "eventType": "ORDER_COMPLETED",
  "orderNo": "CK20260930183000123456",
  "productKey": "vip_dxs",
  "status": "completed",
  "charCount": 12345,
  "failReason": null,
  "completedAt": "2026-09-30T18:36:00.123456",
  "reportUrl": "https://api.llmapi.fit/api/v1/check/orders/CK20260930183000123456/report?token=1789...",
  "reportExpireAt": "2026-10-01T18:36:00.123456"
}

检测失败的通知体（无 reportUrl / reportExpireAt 字段，费用已退回）：

{
  "eventType": "ORDER_FAILED",
  "orderNo": "CK20260930183000123456",
  "productKey": "vip_dxs",
  "status": "failed",
  "charCount": 12345,
  "failReason": "检测失败原因说明",
  "completedAt": "2026-09-30T18:36:00.123456"
}

• 验签：用您的 API Key 对 X-Timestamp + "\n" + 原始请求体 计算 HMAC-SHA256，与 X-Signature 比对
• 通知非 2xx 时按 1m · 5m · 30m · 1h · 6h 重试 5 次
• 幂等：请按 orderNo + eventType 去重

10. 报告下载

两种方式任选：

• 签名直链（推荐）：回调里的 reportUrl 免鉴权直接 GET
• API Key 下载：

GET /api/v1/check/orders/{order_no}/report
Authorization: Bearer YOUR_API_KEY

返回报告文件（zip 压缩包，内含全文对照、详细片段等多份报告文件），重复率等检测结果数值在报告中查看。报告不长期保留，请及时下载保存；过期后返回 report_expired（报告已删除）；报告未生成时返回 {"code": "report_not_ready", "message": "报告尚未生成"}。

11. 快速接入流程

1. 获取 API Key（控制台「APIKEY」页）
2. PUT /api/v1/check/callback-url 配置回调地址（或下单时传 callback_url）
3. POST /api/v1/check/orders 提交检测，记下 order_no
4. 等待回调通知，完成后尽快用 reportUrl 下载报告

转售场景改用两段式：第 3 步加传 auto_submit=false，收到 ORDER_COUNTED 后按 feeYuan 向终端用户收款，再调 POST /orders/{order_no}/confirm 完成检测（完整流程见第 6 节）。