API VERSION 1

客户任务 API

客户使用本站发放的 CDK 提交 AT。请求与响应均为 JSON，CDK 同时作为额度凭证；每成功受理一项任务占用一次额度。

Base URLhttps://ss.sn.cn/api/v1

AT 仅用于任务处理，不会在接口响应中返回。请通过服务端调用接口，并妥善保管客户 CDK。

POST/cdk/validate

校验客户 CDK

提交任务前检查 CDK 状态、可用次数与冻结次数。

请求

curl -X POST 'https://ss.sn.cn/api/v1/cdk/validate' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"LDK-XXXX-XXXX-XXXX"}'

响应

{
  "valid": true,
  "remainingUses": 20,
  "reservedUses": 1,
  "expiresAt": null
}

POST/tasks/submit

批量提交任务

每次提交 1 至 5000 项。每项需要客户 CDK 与 AT；字段 at 也兼容旧名称 accessToken。可传入可选的 idempotencyKey；未传时本站会根据客户 CDK 与 AT 自动生成幂等键，重复请求不会重复冻结额度。本站先将全部有效任务持久化并冻结额度，再立即返回 DURABLY_QUEUED，不等待提炼服务响应；请保存 taskId 并正常轮询，提炼名额释放后会自动补入，无需重新提交。

curl -X POST 'https://ss.sn.cn/api/v1/tasks/submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {"cdk":"LDK-XXXX-XXXX-XXXX","at":"eyJ...","idempotencyKey":"ORDER-10001"},
      {"cdk":"LDK-XXXX-XXXX-XXXX","at":"eyJ..."}
    ]
  }'

受理响应

{
  "total": 2,
  "accepted": 2,
  "reused": 0,
  "rejected": 0,
  "unknown": 0,
  "results": [
    {
      "index": 0,
      "outcome": "ACCEPTED",
      "status": 202,
      "task": {
        "taskId": "ld_7ce6f87c-2dd0-4d88-988a-7404fb5135aa",
        "email": "",
        "status": "RUNNING",
        "businessStatus": "EXTRACTING",
        "statusText": "提炼中",
        "message": "提炼中",
        "phase": "EXTRACTION",
        "extractionStatus": "QUEUED",
        "extractionStatusText": "等待提链",
        "paymentStatus": null,
        "paymentStatusText": null,
        "scannerName": "",
        "terminal": false,
        "progressPercent": 10,
        "createdAt": "2026-10-31T12:00:00.000Z"
      },
      "error": null,
      "code": "DURABLY_QUEUED"
    }
  ]
}

POST/tasks/batch

批量查询任务

使用提交响应中的 taskId 查询最新进度，并同时提交任务所属的客户 cdk。提交后应每 3 至 5 秒调用本接口，直到任务进入终态。/cdk/validate 仅校验额度，不能用于查询任务进度。单次最多查询 500 个任务。提交接口固定采用快速持久化异步受理，不在提交连接中等待提炼结果。

curl -X POST 'https://ss.sn.cn/api/v1/tasks/batch' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"LDK-XXXX-XXXX-XXXX","taskIds":["7ce6f87c-2dd0-4d88-988a-7404fb5135aa"]}'

EXTRACTING提炼中PAYMENT_PENDING提炼成功支付中EXTRACTION_FAILED提炼失败PAYMENT_FAILED支付失败PAYMENT_SUCCEEDED支付成功CANCELED已取消

以上业务状态位于 businessStatus，兼容状态位于 status。需要分别展示提炼和支付时，使用 extractionStatus/extractionStatusText 与 paymentStatus/paymentStatusText；提炼成功进入支付后，extractionStatus 会继续保持 SUCCEEDED。客户接口不会暴露内部接单状态；当 terminal 为 true 时停止轮询。

POST/tasks/list

按 CDK 读取任务记录

返回该客户 CDK 从本站前端或 SDK 提交的最近任务，用于跨浏览器、跨设备同步任务列表。

curl -X POST 'https://ss.sn.cn/api/v1/tasks/list' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"LDK-XXXX-XXXX-XXXX","limit":500}'

GET/results?cdk=LDK-...

查询成功记录

返回指定客户 CDK 关联的成功任务，不返回 AT 或内部处理信息。

curl 'https://ss.sn.cn/api/v1/results?cdk=LDK-XXXX-XXXX-XXXX'

错误处理

400请求格式、数量或 AT 不正确

401 / 403缺少客户 CDK，或客户 CDK 无效、停用、过期、额度不足

404任务不存在或不属于当前 CDK

429请求或登录频率过高

502 / 503任务服务暂不可用，可稍后重试

批量提交可能出现部分成功。客户端应逐项读取 results[].outcome，保存已受理项的 taskId，并对拒绝项按 code 处理。