開發者入口可做的事

ReceiptRoller 的開發者入口，提供將購買、銷售、商品、庫存、廣告、使用者收據等零售資料，從外部系統安全串接的手段。串接手段是 REST API 與 Webhook 兩個。

2 個串接手段

REST API（輪詢型、請求型）

從外部系統向 ReceiptRoller 的伺服器發送 HTTPS 請求，取得、操作資料。以 OAuth 2.0 驗證，使用必要權限範圍的存取權杖呼叫端點。

• 在店鋪業主許可的範圍，可操作商品、訂單、庫存、顧客、優惠券等
• 被核准的合夥人，可參照使用者同意的收據、支出資料
• 適合「想取得現在的狀態」「想更新資料」這樣的使用案例

Webhook（推播型、事件型）

將 ReceiptRoller 端發生的事件（收據發行、更新等），對已登錄的 URL 自動地 POST。外部系統不需要定期輪詢 API，事件發生的瞬間可啟動處理。

• 可與收據發行同時接收對自家伺服器的通知
• 以簽章（HMAC-SHA256）可驗證發送來源
• 失敗時最多重試 4 次自動重試

API 能做的事

依 OAuth 權限範圍區分可存取的資源。以下是代表性的例子。權限範圍的完整一覽請參閱 OAuth 權限範圍一覽。

Webhook 能做的事

訂閱 ReceiptRoller 上的事件，可在外部系統即時處理。

• 收據發行事件 — 在 POS 結帳完成而電子收據被發行的瞬間，對自家伺服器通知
• 收據更新事件 — 退款、取消等收據的狀態改變時通知
• 訂單事件 — 新訂單、狀態變更時通知（店鋪向）

簽章驗證、重試、冪等性的設計等，實作上的注意點請參閱店鋪向 Webhook 指南。

主要的使用案例

關於 SDK、用戶端生成

不提供語言別的專用 SDK。取而代之，將全端點的定義作為 OpenAPI（Swagger）形式的機器可讀規格公開。

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

將這個 URL 傳給 AI 程式設計助手，或匯入 openapi-generator、NSwag、Kiota 等程式碼生成工具，就可以自動生成附型別的 API 用戶端。不需要等待 SDK。

手寫實作的情況，各語言的標準的 HTTP 用戶端與 OAuth 2.0 函式庫的組合就足夠。

• JavaScript / TypeScript: fetch, axios, openid-client
• Python: requests, requests-oauthlib, authlib
• .NET: HttpClient, IdentityModel
• Ruby / PHP / Go: 各語言的標準函式庫 ＋ OAuth 2.0 用戶端

利用開始為止的流程

1. 建立 ReceiptRoller 的帳戶
2. 進行開發者申請，接受核准
3. 在開發者入口登錄應用程式，設定用戶端 ID、用戶端密鑰、重新導向 URL
4. 指定必要的 OAuth 權限範圍實作授權流程
5. 以取得的存取權杖呼叫 API，或登錄 Webhook URL 接收事件

相關指南

• API 驗證指南（OAuth 2.0 授權碼流程）
• OAuth 權限範圍一覽與利用可否
• 錢包應用程式向指南
• 店鋪向 Webhook 指南
• 返回開發者向幫助目次