更新日誌

商戶 API 介面與開發者文件的發布說明。版本依循後端發布 tag。內部基礎建設變更（部署管線、多租戶重構、CI 升級等）只記錄於程式碼倉，刻意不列在此處。

如何閱讀本更新日誌

• 每個版本將變更歸類為 新增、變更、廢棄、移除、安全 與 修正。空白區段會省略。
• 需要商戶端調整的條目以 ⚠ 破壞性變更 開頭。
• 條目盡可能連結到對應的章節。
• 文件站版本依循後端發布 tag。並非每個後端發布都會帶來商戶介面的變更；對商戶不可見的發布會標示為 internal-only，讓版本與 tag 的對應保持連續。

[未發布]

• 文件：Wave 3 — Security、FAQ 與 Changelog 三語（en / zh-Hant / zh-Hans）章節，並新增 i18n 完整性 CI 守門，當章節跨語系不同步時 PR 檢查會失敗。連結將於 PR 合併後補上。

[v0.53.0] — 2026-05-20

新增

• 文件：Wave 2 — Quickstart、Deposits、Withdrawals 與 Callbacks 三語（en / zh-Hant / zh-Hans）章節。包含 5 張 Mermaid 流程圖，涵蓋 deposit-direct、deposit-cashier、withdrawal、callback-handshake 與 error-recovery 序列。章節之間的交叉連結現在涵蓋所有常見商戶情境。

修正

• 文件：Sandbox 章節的端點路徑從 /api/v1/merchant/deposit 修正為 /api/v1/merchant/orders/deposit。回應信封形狀從 {"code": 0} 修正為 {"success": true, "code": "SUCCESS"}，以對齊實際的伺服器回應。三個語系皆受影響。

PR：#89

[v0.52.1] — 2026-05-20

內部發布；無商戶 API 介面或文件變更。（營運主控台的前端 impersonation 橫幅修正，不屬於商戶 API。）

[v0.52.0] — 2026-05-20

新增

• 文件：Wave 1 — Errors 與 Sandbox 三語章節。Errors 章節是商戶 API 的標準 HTTP 狀態碼 + 業務碼參考；Sandbox 章節記錄測試憑證、fixture 金額與手動 callback 觸發方式。
• 程式碼樣本：verify.{sh,py,php,ts} callback 簽章驗證樣本新增於 docs-site/shared/code-samples/。由 Callbacks 章節引用（該章節於 v0.53.0 上線）。
• CI：跨語言樣本一致性測試在 CI（docs-pr-check.yml）強制執行 — 四個 verify.* 樣本必須接受相同的 fixture 並回傳相同結果，避免各語言版本偏離。

PR：#86

[v0.51.0] — 2026-05-19

新增

• 文件：docs.open-pay.co 基礎建設上線。VitePress 站點含三個語系（en / zh-Hant / zh-Hans）、Authentication 章節（EN seed）、由過濾後的 OpenAPI 匯出自動產生的 API Reference、側欄/導覽、搜尋，以及 PR/release CI 部署至 Cloudflare Pages。
• 程式碼樣本：sign.{sh,py,php,ts} 請求簽章樣本新增於 docs-site/shared/code-samples/。由 Authentication 章節引用 — 四個樣本以相同輸入產生相同簽章，並由 CI 檢查。
• 後端：新增 python -m app.cli export-openapi --scope merchant CLI 以匯出過濾後的 OpenAPI（僅商戶 tag 路由，排除內部 admin/platform 路由）。屬於支援 API Reference 建置的內部工具；商戶不會直接呼叫。

PR：#78

[v0.50.0] — 2026-05-19

內部發布；無商戶 API 介面或文件變更。（OL 環境的集中式日誌基礎建設與 platform-console picker 修正；兩者皆不影響商戶 API。）

更早期的版本

v0.50.0 之前的發布歷史早於商戶文件站。更早的商戶 API 變更未在此編目；若你需要特定端點、callback payload 或 schema 欄位的歷史脈絡，諮詢你的客戶經理。