站點對接說明

更新時間：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：如何更新上游商品的庫存和價格？

在「商品映射」頁面選擇對應連線，點擊「同步商品」即可從上游拉取最新的商品資訊、庫存和價格。