API 驗證指南

驗證指南

ReceiptRoller API 使用 OAuth 2.0 授權碼流程。 伺服器端的開發者登錄應用程式，商業帳戶業主許可存取後，開發者就可以取得權杖呼叫 API。

步驟1：登錄應用程式

1. 登入 ReceiptRoller 帳戶
2. 移動到 商業帳戶詳細 → ⋮ 選單 → 開發者應用程式
3. 點擊 建立應用程式
4. 輸入、選擇應用程式名、重新導向 URI、必要的 API 權限範圍
5. 建立後，client_id 與 client_secret 會被發行

步驟2：將商業帳戶業主重新導向至授權畫面

商業帳戶業主將帳戶串接至應用程式時，將瀏覽器重新導向至以下的 URL：

GET https://your-domain/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REDIRECT_URI
    &response_type=code
    &scope=store.products.read store.orders.read
    &state=RANDOM_STATE_STRING

商業帳戶業主會看到顯示了應用程式名與被要求的存取權限的同意畫面。可選擇許可或拒否。

步驟3：接收授權碼

被許可的情況，商業帳戶業主的瀏覽器會被重新導向至 redirect_uri：

GET https://your-app.com/callback
    ?code=AUTHORIZATION_CODE
    &state=RANDOM_STATE_STRING

被拒否的情況：

GET https://your-app.com/callback
    ?error=access_denied
    &state=RANDOM_STATE_STRING

步驟4：將碼交換為權杖

從伺服器端（而非瀏覽器），以下面的 POST 請求將碼交換為存取權杖：

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

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

成功回應（200）：

{
    "accessToken": "aBcDeFgH1234567890...",
    "refreshToken": "xYzAbCdEfG098765...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "scope": "store.products.read store.orders.read"
}

步驟5：呼叫 API

將存取權杖含入 Authorization 標頭請求：

GET /api/v1/store/products
Authorization: Bearer aBcDeFgH1234567890...
Content-Type: application/json

API 會回傳繫在許可應用程式的商業帳戶的資料。只能存取以被核准的權限範圍許可的資料。

步驟6：刷新過期權杖

存取權杖的有效期限過了的情況，使用刷新權杖取得新的權杖配對：

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

{
    "grantType": "refresh_token",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "refreshToken": "xYzAbCdEfG098765..."
}

回應形式與步驟4相同。舊的存取權杖與刷新權杖會被無效化，回傳新的配對。

權杖的取消

要取消存取權杖或刷新權杖：

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

{
    "token": "要取消的權杖",
    "clientId": "YOUR_CLIENT_ID"
}

商業帳戶業主可從帳戶設定隨時取消應用程式的存取。

錯誤回應

可利用的權限範圍

Store（店鋪）

CRM（顧客關係管理）

SNS / 分析

流程圖

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  您的應用程式 │     │ 商業帳戶     │     │  ReceiptRoller  │
│  （開發者）  │     │ 業主        │     │  平台表單        │
└──────┬───────┘     └──────┬───────┘     └────────┬─────────┘
       │                    │                      │
       │  1. /oauth/authorize 重新導向              │
       │───────────────────▶│──────────────────────▶│
       │                    │                      │
       │                    │  2. 顯示同意畫面     │
       │                    │◀─────────────────────│
       │                    │                      │
       │                    │  3. 許可             │
       │                    │──────────────────────▶│
       │                    │                      │
       │  4. 以 ?code=授權碼 重新導向               │
       │◀───────────────────│◀─────────────────────│
       │                    │                      │
       │  5. POST /api/v1/auth/token               │
       │  （code ＋ client_id ＋ client_secret）    │
       │──────────────────────────────────────────▶│
       │                                           │
       │  6. { accessToken, refreshToken }         │
       │◀──────────────────────────────────────────│
       │                                           │
       │  7. GET /api/v1/store/products            │
       │  Authorization: Bearer {accessToken}      │
       │──────────────────────────────────────────▶│
       │                                           │
       │  8. { data: [...] }                       │
       │◀──────────────────────────────────────────│

安全性的最佳實踐

• client_secret 請只保管在伺服器端。絕對不要含入前端的程式碼或行動應用程式。
• 為防止 CSRF 攻擊，請務必驗證 state 參數。
• 行動應用程式或單頁應用程式的情況，請使用 PKCE（code_challenge / code_verifier）。
• 權杖請安全保管。請勿將存取權杖記錄於日誌，或含入 URL。
• 為避免服務的中斷，請在有效期限過期前實作權杖的刷新。
• 請只請求應用程式實際需要的權限範圍。