站点对接说明

更新时间：2026-04-01

本文用于说明 Dujiao-Next 站点之间如何进行对接与串货，帮助站长快速跑通从"申请凭证"到"异步采购 + 多级回调"的完整流程。

如需了解 Open API 的接口参数与签名算法，请参阅 Open API 接口文档。

1. 角色与链路

角色	说明
对接方（A 站）	拉取上游商品，在本站售卖。以采购方身份调用上游 API
被对接方（B 站）	提供商品与 API，接收 A 的采购请求并按本地流程处理
更上游（C/D/...）	B 也可能继续向自己的上游采购，形成多级链路

说明：

• 系统支持购物车混合订单，一个父订单下可同时包含本地商品和多个上游来源商品（拆分为子单处理）。
• 采购单 source_type 区分：
  • outbound：本站向上游采购；
  • inbound：本站接收下游采购。

2. 标准流程

A 站（对接方）                    B 站（被对接方）
─────────────                    ─────────────
1. 管理员创建连接 ───────────────→
2. 测试连接 (POST /ping) ──────→  验证签名，返回站点信息
3. 拉取商品列表 ───────────────→  返回可售商品与 SKU
4. 建立商品映射
5. 用户下单 + 支付
6. 异步采购 (POST /orders) ────→  钱包扣款，创建本地订单
7.                ←─────────────  回调通知（状态/交付内容）
8. 更新本地订单状态

若 B 站该商品也有上游映射，B 会继续异步向 C 站采购，链路可无限级延伸。最终履约节点交付后，状态与交付内容逐级回调，直到回传到 A 站。

3. 被对接方（B 站）需要做什么

3.1 管理 API 凭证

后台路径：系统管理 → API 凭证管理

每个用户最多拥有一组 API 凭证（API Key + API Secret），凭证需要由管理员审核后才能使用。

用户侧：

• 前台个人中心申请 API 凭证
• 申请后状态为"待审核"，管理员审核通过后方可使用
• API Secret 只在创建时展示一次，请立即保存

管理员侧：

• 在后台查看所有用户的 API 凭证申请
• 审核操作：通过 / 拒绝（可填写拒绝理由）
• 可随时启用或停用已通过的凭证

3.2 设置站点信息

确保站点可通过公网访问，对接方会使用你的站点地址 + /api/v1/upstream 作为 API 入口。

4. 对接方（A 站）如何配置

4.1 新增连接

后台路径：对接管理 → 连接管理 → 新增

字段	填写说明
连接名称	自定义，便于区分来源站点
站点地址	填 B 站根地址，如 https://b.example.com
协议类型	使用默认值（Dujiao OpenAPI）
API Key	B 站用户的 API Key
API Secret	B 站用户的 API Secret
回调地址	A 站接收回调的公网地址
重试次数	采购失败时的最大重试次数
重试间隔	每次重试的等待时间（秒），支持多级配置

注意：

• "站点地址"填根地址即可，系统会自动拼接 /api/v1/upstream 前缀。
• 创建后可点击"测试连接"验证配置是否正确。

4.2 拉取商品与建立映射

后台路径：对接管理 → 商品映射

操作流程：

1. 选择已建立的连接，点击"同步商品"从上游拉取商品列表。
2. 选择需要映射的上游商品，建立本地商品与上游商品/SKU 的映射关系。
3. 支持批量导入映射关系。
4. 按你的运营策略设置本地价格与展示信息。
5. 启用映射后，商品将自动以上游库存对外展示。

映射说明：

• 映射建立后，本地商品的交付类型自动标记为"上游对接"。
• 商品列表中会显示上游实时库存，支持"自动发货"或"人工发货"两种展示（取决于上游商品的实际交付类型）。
• 可随时同步更新上游商品信息与库存。

4.3 采购单管理

后台路径：对接管理 → 采购单管理

管理所有向上游发起的采购订单：

• 查看采购状态（待处理 / 已完成 / 失败 / 已取消）
• 查看失败原因与重试情况
• 支持手动重试失败的采购单
• 按来源连接、状态等条件筛选

4.4 对账中心

后台路径：对接管理 → 对账中心

对账功能帮助你核实采购数据一致性：

• 支持按时间段发起对账
• 对账类型：金额对账 / 全量对账
• 查看对账结果与差异明细

5. 业务规则

5.1 交付规则

• 映射商品的交付完全依赖上游回调，不允许本地手动发货或本地自动发货。
• 上游交付后，系统自动通过回调更新本地订单状态与交付内容。
• 前台用户不会看到"上游对接"标识，来源信息仅后台可见。

5.2 取消规则

• 取消流程必须"上游先成功，本地后取消"：
  • 有出站采购单时，先调用上游取消接口；
  • 上游返回不可取消，则本地不可取消、不可退款。

5.3 异常处理

• 上游采购失败时，系统仅标记异常供管理员处理，不会自动取消或退款。
• 异步采购与回调链路不影响用户正常下单体验。
• 管理员可在采购单管理中查看失败原因并手动重试。

6. 签名认证

所有 API 请求使用 HMAC-SHA256 签名认证，需携带以下请求头：

Header	说明
Dujiao-Next-Api-Key	API Key
Dujiao-Next-Timestamp	Unix 时间戳（秒）
Dujiao-Next-Signature	HMAC-SHA256 签名

签名字符串格式：

{METHOD}\n{PATH}\n{TIMESTAMP}\n{MD5(BODY)}

• 时间戳误差不能超过 60 秒
• 详细签名算法与代码示例请参阅 Open API 接口文档

7. 常见问题

Q1：测试连接返回 401

优先检查：

• API Key / API Secret 是否填错
• 凭证是否已被管理员审核通过
• 凭证是否处于启用状态
• 站点地址是否可公网访问

Q2：下单时报签名错误

优先检查：

• 请求是否携带了三个必要的签名头（Dujiao-Next-Api-Key、Dujiao-Next-Timestamp、Dujiao-Next-Signature）
• 时间戳是否偏差超过 60 秒
• 签名字符串格式是否正确（注意 Body MD5 计算）

Q3：用户下单成功但采购失败

常见原因：

• B 站对接用户的钱包余额不足
• 上游商品库存不足或已下架
• 商品映射关系错误（商品 ID / SKU ID 不匹配）

处理建议：

• 在"采购单管理"中查看失败原因
• 修正问题后可手动重试采购

Q4：为什么映射商品不能本地手工发货？

映射商品已声明依赖上游履约，系统强制等待上游回调，避免本地与上游状态不一致。

Q5：为什么取消按钮点了但订单没取消？

对接订单取消前会先执行上游取消。上游不可取消时，本地会拒绝取消，以保证资金与状态一致。

Q6：如何更新上游商品的库存和价格？

在"商品映射"页面选择对应连接，点击"同步商品"即可从上游拉取最新的商品信息、库存和价格。