錢包應用程式向：以 OAuth 取得使用者的收據的指南

是持有自家的 iOS 應用程式、Android 應用程式、LINE Mini App 的店鋪、品牌向的開發者指南。
使用 ReceiptRoller 的 OAuth 驗證與 API，就可以在自己的店鋪發行的數位收據，在使用者的同意下取得，並顯示於自家應用程式。

使用案例

例如，可以有這樣的用法。

• 咖啡連鎖店在自家應用程式顯示「購入紀錄」
• 藥妝店在 LINE Mini App 讓人看「我的收據」
• EC 品牌在 Android 應用程式將月次的支出摘要顯示於儀表板
• 購買完成同時以 Webhook 對自家伺服器發送收據資料

機制的概要

使用者 → 自家應用程式 → OAuth同意畫面（ReceiptRoller）
                              ↓
                        存取權杖發行
                              ↓
              自家應用程式 → 收據API → 數位收據取得

自家應用程式以 ReceiptRoller 的 OAuth 2.0 流程取得存取權杖。
使用取得的權杖呼叫 API，會回傳該使用者在自己的店鋪收到的收據。

步驟1：登錄應用程式

1. 登入 ReceiptRoller 的開發者入口
2. 從「登錄應用程式」發行用戶端 ID 與密鑰
3. 設定 redirect_uri（授權後的重新導向對象）

步驟2：實作 OAuth 授權碼流程

2-1. 取得授權碼

將使用者以瀏覽器誘導至以下的 URL。

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=user.receipts.read user.spending.read
  &state=RANDOM_STRING

使用者在 ReceiptRoller 的同意畫面點擊「許可」，redirect_uri 會回傳授權碼。

YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STRING

2-2. 將碼交換為權杖

POST /api/v1/auth/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "code": "AUTH_CODE",
  "redirectUri": "YOUR_REDIRECT_URI"
}

回應：

{
  "accessToken": "eyJ...",
  "refreshToken": "def50200...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "user.receipts.read user.spending.read"
}

2-3. 權杖的刷新

存取權杖的有效期限過了就刷新。

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "def50200...",
  "clientId": "YOUR_CLIENT_ID"
}

步驟3：取得收據

所有 API 請求附加 Authorization: Bearer {access_token} 標頭。

收據一覽（依月篩選對應）

GET /api/v1/user/receipts?year=2026&month=4
Authorization: Bearer {access_token}

收據詳細（含明細、店鋪資訊）

GET /api/v1/user/receipts/{id}
Authorization: Bearer {access_token}

月間支出摘要

GET /api/v1/user/receipts/summary?year=2026&month=4
Authorization: Bearer {access_token}

權限範圍：user.spending.read
回傳依類別的內容、與前月比、收據張數。可用於儀表板畫面的構築。

步驟4：以 Webhook 即時接收

取代輪詢 API，可在收據被發行的瞬間對自家伺服器接收通知。從開發者入口登錄 Webhook 端點，使用者的收據每次被建立、更新就會 POST。

安全性驗證

為確認接收到的 Webhook 的正當性，請驗證 X-RR-Signature 標頭。

import hmac, hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

必要的權限範圍一覽

對應平台表單

常見問題

Q. 只會回傳自己的店鋪的收據嗎？
A. 是。API 會回傳以 OAuth 驗證的使用者收到的收據當中，只有繫在您的店鋪的那些。無法取得他店的資料。

Q. 使用者取消同意的情況呢？
A. 存取權杖會變無效。之後的 API 請求會回傳 401。

Q. Webhook 有重送嗎？
A. 自家伺服器沒回傳 2xx 的情況，最多自動重試 4 次。

下一步

• 技術性的提問請向支援洽詢