# 岛民溯源 API V3 — 第三方对接文档 > 版本: v3.0 | 更新: 2026-07-30 | 状态: 正式上线 --- ## 概述 岛民溯源系统为第三方商家/平台提供标准 REST API，支持： - **商品溯源注册** — 为每件商品生成唯一溯源码 - **供应链事件记录** — 记录生产/加工/运输/质检/销售等环节 - **溯源轨迹查询** — 消费者/商家查询完整溯源链路 - **数据存证** — 数据哈希存证，可下载司法级证书 所有 API 通过 HTTPS 调用，使用 API Key 认证。 --- ## 快速开始 ### 1. 获取 API Key 联系岛民科技获取 API Key，或通过管理后台自助生成。 API Key 格式示例: ``` TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB ``` ### 2. 调用 API 每次请求在 HTTP Header 中添加: ``` X-API-Key: TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB ``` ### 3. Base URL ``` 生产环境: https://daomin.cloud/api/v3/traceability 测试环境: https://daomin.cloud/api/v3/traceability ``` 所有请求返回统一格式: ```json { "code": 0, "message": "ok", "data": { ... } } ``` 错误响应: ```json { "code": -1, "message": "错误描述" } ``` HTTP 状态码: | 状态码 | 含义 | |--------|------| | 200 | 请求成功 | | 400 | 请求参数错误 | | 401 | API Key 缺失或无效 | | 403 | API Key 已禁用/过期 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | --- ## API 列表 ### 1. 注册溯源商品 为商品注册唯一溯源码，生成 `PXXXXXXXX` 格式的溯源码。 ``` POST /api/v3/traceability/product/register ``` **请求体 (JSON):** | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `name` | string | 是 | 商品名称 | | `origin` | string | 是 | 产地 | | `producer` | string | 否 | 生产方（不填自动生成） | | `product_id` | string | 否 | 自定义溯源码（不填自动生成） | **请求示例:** ```bash curl -X POST "https://daomin.cloud/api/v3/traceability/product/register" \ -H "Content-Type: application/json" \ -H "X-API-Key: TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB" \ -d '{ "name": "海南芒果", "origin": "海南省三亚市", "producer": "岛民农业科技有限公司" }' ``` **响应示例:** ```json { "code": 0, "message": "ok", "data": { "product_id": "P794619C9", "name": "海南芒果", "trace_url": "https://daomin.cloud/trace.html?product=P794619C9" } } ``` `trace_url` 可直接嵌入二维码或链接，供消费者扫码查看溯源信息。 --- ### 2. 记录溯源事件 为已注册商品添加供应链事件。 ``` POST /api/v3/traceability/event/record ``` **请求体 (JSON):** | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `product_id` | string | 是 | 商品溯源码 | | `event_type` | string | 是 | 事件类型（见下方列表） | | `location` | string | 否 | 事件发生地点 | | `data` | string | 否 | 事件详情 | | `operator` | string | 否 | 操作人（默认"系统"） | **事件类型枚举:** | 类型 | 中文 | 含义 | |------|------|------| | `PRODUCE` | 生产 | 种植/养殖/生产 | | `PROCESS` | 加工 | 分拣/包装/加工 | | `TRANSPORT` | 运输 | 物流运输 | | `STORE` | 仓储 | 入库/存储 | | `INSPECT` | 质检 | 检验/检测 | | `SALE` | 销售 | 上架/销售 | | `TRANSFER` | 移交 | 保管权转移 | **请求示例:** ```bash curl -X POST "https://daomin.cloud/api/v3/traceability/event/record" \ -H "Content-Type: application/json" \ -H "X-API-Key: TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB" \ -d '{ "product_id": "P794619C9", "event_type": "PRODUCE", "location": "海南三亚芒果园", "data": "2026年7月采摘，一级果，糖度18.5", "operator": "张三" }' ``` **响应示例:** ```json { "code": 0, "message": "事件记录成功", "data": null } ``` --- ### 3. 查询商品溯源轨迹 获取商品信息和完整供应链事件列表。 ``` GET /api/v3/traceability/product/{product_id} ``` **路径参数:** | 参数 | 类型 | 说明 | |------|------|------| | `product_id` | string | 商品溯源码 | **请求示例:** ```bash curl "https://daomin.cloud/api/v3/traceability/product/P794619C9" \ -H "X-API-Key: TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB" ``` **响应示例:** ```json { "code": 0, "message": "ok", "data": { "product": { "product_id": "P794619C9", "name": "海南芒果", "origin": "海南省三亚市", "producer": "岛民农业科技有限公司", "current_custodian": "张三", "created_at": "2026-07-30 20:31:16" }, "events": [ { "type": "PRODUCE", "location": "海南三亚芒果园", "data": "2026年7月采摘，一级果", "operator": "张三", "time": "2026-07-30 20:35:00" }, { "type": "TRANSPORT", "location": "三亚→海口冷链", "data": "全程2-8°C冷链运输", "operator": "王五", "time": "2026-07-31 08:00:00" } ], "trace_url": "https://daomin.cloud/trace.html?product=P794619C9" } } ``` --- ### 4. 提交数据存证 将数据哈希存证到岛民链，返回存证编号和证书下载链接。 ``` POST /api/v3/traceability/notary/deposit ``` **请求体 (JSON):** | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `title` | string | 是 | 存证标题 | | `content` | string | 是 | 存证内容（系统自动计算 SHA-256 哈希） | | `depositor` | string | 否 | 提交人/机构（默认"第三方用户"） | **请求示例:** ```bash curl -X POST "https://daomin.cloud/api/v3/traceability/notary/deposit" \ -H "Content-Type: application/json" \ -H "X-API-Key: TR-D9AD1E4D961B7DD3A41C9F2904CF1FCB" \ -d '{ "title": "芒果批次溯源数据", "content": "{\"product_id\":\"P794619C9\",\"events\":[{\"type\":\"PRODUCE\",\"location\":\"海南三亚\"}]}", "depositor": "岛民农业" }' ``` **响应示例:** ```json { "code": 0, "message": "ok", "data": { "deposit_id": "DM-Z639WJ5E", "content_hash": "46bc1fddf225553e13bc96b093c4dfadb1b92d37b97a96ec65ce6acd5786609d", "certificate_url": "https://daomin.cloud/api/notary/deposit/DM-Z639WJ5E/certificate", "verify_url": "https://daomin.cloud/notary/?deposit_id=DM-Z639WJ5E" } } ``` `certificate_url` 返回带公章和 QR 码的 A4 存证证明书（PNG 图片）。 `verify_url` 可在浏览器中验证存证详情。 --- ## 常见场景 ### 场景一：农产品溯源 ``` ① 注册商品 → ② 记录生产事件 → ③ 记录质检事件 → ④ 记录运输事件 → ⑤ 记录销售事件 ``` 每次新环节调用 `event/record`，消费者扫码即可看到完整生命周期。 ### 场景二：溯源二维码打印 注册商品后，将 `trace_url` 生成 QR 码印刷在包装上： - 消费者微信扫码直接查看溯源信息 - 支持 `?product=P794619C9` 参数直达 ### 场景三：司法存证 每批次溯源完成后，调用 `notary/deposit` 将全量数据哈希存证： - 系统自动计算 SHA-256 哈希 - 生成司法级存证证书（带公章 + QR码） - 区块链不可篡改锚定（待链修通后自动同步） --- ## 错误码参考 | code | 说明 | |------|------| | 0 | 成功 | | -1 | 通用错误（查看 message 字段） | **HTTP 401 原因:** - 未提供 `X-API-Key` 请求头 - 提供的 API Key 不存在 **HTTP 403 原因:** - API Key 已被管理员吊销 - API Key 已过期 --- ## 限制 | 限制项 | 说明 | |--------|------| | 每商品事件数 | 不限 | | 单次批量注册 | 最多 50 个（内部 API） | | 请求频率 | 建议 ≤ 100次/分钟 | | 数据大小 | 单次存证 ≤ 1MB | --- ## 架构说明 ``` 第三方商城/App/小程序 │ ├─ HTTPS + X-API-Key │ ┌────▼──────────────────────────┐ │ 岛民溯源 API (daomin.cloud) │ │ ┌─────────────────────────┐ │ │ │ MySQL 持久化 (主存储) │ │ │ └─────────────────────────┘ │ │ ┌─────────────────────────┐ │ │ │ SHA-256 哈希存证 │ │ │ │ 区块链锚定 (信任层) │ │ │ └─────────────────────────┘ │ └───────────────────────────────┘ │ 消费者扫码 → trace.html 页面 ``` - **所有数据存 MySQL**，毫秒级响应 - **SHA-256 哈希**作为数据完整性凭证 - **区块链存证**做不可篡改信任锚（待链修通后自动同步存证 hash） - **消费者扫码**直接看，无需登录 --- ## 联系我们 岛民科技集团（海南）有限公司 - 官网: https://daomin.cloud - 热线: 400-088-0511 - 溯源演示: https://daomin.cloud/trace.html?product=PE7DCAF08