ReBate Pay Docs版本策略與更新紀錄
API 怎麼標版本、什麼算破壞性變更、以及目前的更新紀錄。
版本怎麼標
API 版本用日期字串標示（例如 2026-09-29），透過每個回應的 x-rebatepay-version 標頭帶回來；路徑一律在 /api 底下。目前只有一個在跑的版本，還沒有版本協商或多版本並存機制。
什麼算破壞性變更
以下算破壞性變更，會在真的推出前提前公告，並給遷移說明：
- 移除既有欄位，或改變欄位的型別／意義
- 移除既有端點，或改變它的必填參數
- 改變既有錯誤碼原本代表的意思
- 改變分頁、排序、篩選參數的預設行為
以下不算破壞性變更，隨時可能發生，你的程式碼不應該假設它們不會變：
- 新增回應欄位（既有欄位不受影響）
- 新增端點、新增 scope
- 新增錯誤碼（既有錯誤碼行為不變）
- 調整
error.message／error.nextAction的文字措辭
淘汰政策
目前產品仍在 Sandbox-only 階段，還沒有任何端點被淘汰過。等正式環境開放、開始有版本演進時，淘汰的端點／欄位會維持至少一段公告期仍可運作，並在回應裡標示淘汰狀態，而不是直接關閉。
更新紀錄
| 日期 | 內容 |
|---|---|
2026-09-29 | 目前 API 版本。破壞性變更：路徑改為 /api/{資源}[/{資源Id}][/{動作}]（例如 /api/PaymentLink、/api/Subscription/{subscriptionId}/Cancel），舊的 /v1/... 路徑已移除；更新改用 PUT；列表改用 page／pageSize／orderBy／orderDirection／createdFrom／createdTo，回應帶 totalCount、totalPages；成功回應為 { data }、失敗為 { error }；列舉值改為 PascalCase；Webhook 事件的 created 改為 createdAt；後台與錢包 API 改用 JWT + Refresh Token。 |
2026-08-30 | 第一個 API 版本（/v1，已由 2026-09-29 取代）。 |
這頁會隨著實際上線的變更持續更新——如果你在這裡沒看到某個你記得的變更，代表它還沒有正式定案，不要提前依賴。