API 參考與文件的閱讀方式

ReceiptRoller 的開發者向文件，依目的大致有 4 個入口。本幫助解說概念與使用案例，端點的正確規格在參考、不明點在社群，這樣的分別使用。

4 個入口

1. 開發者幫助（這個網站）

現在正在讀的網站。彙整了概念的說明、實作方針、依使用案例的進行方式。不是「特定端點的規格」而是為了知道「整體如何製作」的東西。

• 初次的人從開發者入口可做的事開始
• 可取得哪個領域的資料看可利用的資料領域
• OAuth 權限範圍的一覽看OAuth 權限範圍一覽與利用可否
• 具體的實作進行方式從目次到各指南

2. API 頂頁

https://receiptroller.io/zh-Hant-TW/api/top

ReceiptRoller API 的頂頁。將常用的代表性端點（人氣的 API），以簡單的範例附帶一覽化。

• 這樣用 — 「總之想取得交易資料」「取得使用者收據的端點是哪個？」這樣、想以最短著手時的入口
• 各端點會顯示必要的權限範圍與範例請求
• 需要詳細規格的情況，可從各端點轉移到下節的參考

3. API 參考（Swagger / OpenAPI）

https://receiptroller.io/docs/api/reference

全端點的完整的參考。以 OpenAPI（Swagger）規格生成，參數、請求本體、回應本體、錯誤碼全部可確認。

• 這樣用 — 確認「這個參數可省略？」「回應的正確 JSON 構造是？」「這個端點回傳什麼錯誤？」時
• 依類別（Store / CRM / SNS / Analytics / User / Survey 等）整理
• 各端點以徽章明示必要的權限範圍
• 以「Try it out」按鈕，可從瀏覽器直接試請求（需權杖）

OpenAPI 規格（機器可讀）的直接取得

作為參考來源的 OpenAPI 規格本身，以下列 URL 公開。

https://receiptroller.io/openapi/v1.json

• 傳給 AI 程式設計助手 — 只要傳這個 URL，就會讀取端點規格幫你寫呼叫程式碼或 API 用戶端
• 匯入程式碼生成工具 — 以 openapi-generator、NSwag、Kiota 等可自動生成附型別的用戶端
• 匯入 Postman / Swagger UI — 作為集合匯入可用於運作確認

Swagger 的高效使用方式

• 以左側邊欄縮限領域 — 以 Store / CRM / Analytics 等標籤只顯示該領域
• 關鍵字搜尋 — 橫斷搜尋端點名、標籤、說明文
• Schema 區段 — 獨立確認回應中含的物件構造
• 伺服器切換 — 正式、預備等環境以下拉可切換

4. 開發者社群

https://receiptroller.io/zh-Hant-TW/developers/community

可與開發者同儕、營運團隊質疑應答的社群。可確認文件無法解決的疑問，或其他開發者是否在同一件事上困擾。

• 提問前 — 請以關鍵字搜尋確認既有的提問。同一疑問可能已解決
• 提問的投稿方法 — 在社群發問
• 回答的接收方式 — 接收提問的回答
• 來自營運團隊的回答會附「Staff」徽章
• 機密資訊（用戶端密鑰、存取權杖等）請勿含入本文

分別使用的例子

實際的開發流程中，組合這些使用較高效。

• 初次接觸 → 在開發者幫助（這個網站）讀使用案例指南
• 總之想動 → 從 API 頂頁選人氣端點試範例
• 進入正式實作 → 以 Swagger 參考確認正確規格同時編碼。使用 AI 助手的情況傳 openapi/v1.json
• 規格上迷惘了 → 在社群搜尋既有提問 → 沒有的話投稿
• 正式發布前 → 再確認開發者幫助的「運用與安全性」

覺得文件舊了的話

ReceiptRoller 持續地追加機能，因此偶爾會在幫助與參考之間記述出現乖離。規格的正確在於總是 API 參考（Swagger）。實際的回應與幫助的記述不同的情況，請信用參考側。

有明顯的錯誤或改善的提案的話請向社群或支援告知。

相關指南

• 開發者入口可做的事（API、Webhook）
• 可利用的資料領域
• 利用開始為止的流程
• OAuth 權限範圍一覽與利用可否
• 返回開發者向幫助目次