下载中心/接口清单

接口清单

下载原文件

样品申请与追踪 · 接口清单

说明:以下为接口契约草案,落地时统一走站点既有数据访问层,字段命名与数据库表保持一致。所有接口需带站点身份头,错误返回统一 { code, message }。

1. 样品任务

创建申请

POST /sample_task

{
  "productId": "string|null",
  "supplierId": "string",
  "layers": 4,
  "material": "FR-4",
  "boardThickness": 1.6,
  "copperWeight": 1,
  "size": "100x100",
  "quantity": 10,
  "surfaceFinish": "HASL",
  "impedance": "50±10%",
  "expectedDate": "2026-12-01",
  "receiver": { "name": "string", "phone": "string", "address": "string" },
  "remark": "string"
}

返回:{ id, status: "submitted", quota: { total, used, remain } } 校验:数量 1–200;板层 1–32;供应商必须处于可接单状态;配额不足返回 SAMPLE_QUOTA_EXCEEDED。

查询列表

GET /sample_task?role=buyer|supplier&status=&keyword=&page=1&pageSize=20 返回:{ list: SampleTask[], total }

查询详情

GET /sample_task/{id} → { task, logs, defects, quota }

供应商响应

POST /sample_task/{id}/accept

{ "unitPrice": 120, "leadTimeDays": 5, "shipDate": "2026-12-05", "remark": "string" }

POST /sample_task/{id}/reject → { "reason": "string" }

状态推进

POST /sample_task/{id}/transition

{ "to": "in_production|shipped|received|passed|conditional|failed|rework|refunded|cancelled|closed", "note": "string" }

约束:服务端按状态机校验,非法流转返回 SAMPLE_STATUS_INVALID。

验收

POST /sample_task/{id}/acceptance

{ "result": "passed|conditional|failed", "note": "string" }

failed 时必须已存在至少一条瑕疵记录,否则返回 SAMPLE_DEFECT_REQUIRED。

2. 流程日志

GET /sample_flow_log?taskId= POST /sample_flow_log → { taskId, node, role, operator, note, attachmentUrl } 约束:日志只追加,不提供更新与删除接口。

3. 样品配额

GET /sample_quota?supplierId= → { total, used, frozen, remain, resetAt } POST /sample_quota/adjust → { supplierId, delta, reason }(仅运营,走管理后台 CRUD)

4. 瑕疵记录

POST /sample_defect

{
  "taskId": "string",
  "defectType": "开短路|孔壁|阻焊|字符|板翘|尺寸|其他",
  "location": "string",
  "severity": "low|medium|high",
  "imageUrls": ["string"],
  "expectation": "rework|refund|discuss",
  "description": "string"
}

GET /sample_defect?taskId= POST /sample_defect/{id}/response → { "action": "rework|refund|discuss", "note": "string" }

5. 错误码

码场景
SAMPLE_QUOTA_EXCEEDED当周配额不足
SAMPLE_STATUS_INVALID非法状态流转
SAMPLE_DEFECT_REQUIRED验收不通过但缺少瑕疵记录
SAMPLE_SUPPLIER_CLOSED供应商暂停接单
SAMPLE_TASK_LOCKED任务已关闭,禁止修改
SAMPLE_FORBIDDEN非任务关联方操作

6. 边界说明

  • 附件字段 attachmentUrl / imageUrls 依赖对象存储;未开通时仅保存文件名与说明文本。
  • 不提供支付、退款资金流转接口;退款状态由线下确认后在管理中登记。
  • 不提供短信、邮件、推送接口;站内仅以列表标记与角标提示。