端點與版本管理

基底 URL

正式： https://api.receiptroller.io/v1
測試： https://api-staging.receiptroller.io/v1

OAuth 授權端點為另一主機。

授權： https://receiptroller.io/oauth/authorize
權杖： https://receiptroller.io/oauth/token

URL 結構

/v{版本}/{資源}[/{ID}][/{子資源}]

例：
GET  /v1/receipts                  ← 收據一覽
GET  /v1/receipts/rcp_xyz123       ← 個別收據
GET  /v1/receipts/rcp_xyz123/items ← 收據的明細
POST /v1/products                  ← 商品建立

版本管理方針

• 採用 URL 路徑方式（/v1/...）。不使用標頭方式
• 向後相容的變更（欄位追加等）在同一版本內實施
• 破壞性變更（欄位刪除、型別變更、URL 變更）作為新版本（/v2）提供
• 新版本公開後，舊版本最少 12 個月並行運行

視為向後相容的變更

• 對回應追加新欄位
• 追加新端點
• 追加選填請求參數
• 對既有錯誤碼追加新的碼

用戶端實作時做成忽略未知欄位的話，較易維持相容性。

破壞性變更的範例

• 既有欄位的刪除、名稱變更
• 欄位的型別變更（string → number 等）
• 必填請求參數的追加
• 驗證方式的變更
• 速率限制的大幅調降

廢止預告與支援期間

廢止預告透過開發者入口網站的「公告」、電子郵件、Sunset 標頭通知。

現行版本的確認

回應標頭 X-RR-Api-Version 中包含目前處理的版本。

HTTP/1.1 200 OK
X-RR-Api-Version: 2026-04-01
Content-Type: application/json

相關指南

• 請求與回應的基本
• 錯誤碼與重試指引
• API 參考與文件的閱讀方式
• 返回開發者幫助中心