OAuth 權限範圍一覽與利用可否
以一覽彙整了 ReceiptRoller 的 OAuth API 可指定的所有權限範圍，與各權限範圍被授予哪種類型的應用程式。登錄 OAuth 應用程式前，或組立授權 URL 前請確認。
OAuth 權限範圍一覽與利用可否
ReceiptRoller 的 API，依 OAuth 2.0 的權限範圍控制可存取的資源。登錄應用程式時與誘導使用者到授權畫面時，請以最小限度只指定必要的權限範圍。權限範圍可以半形空格分隔複數指定。
權限範圍的分類
權限範圍依目的分成 4 個類別。
- Store 系 — 店鋪、商業帳戶的商業資料（商品、訂單、庫存、預約、員工等）
- CRM 系 — 顧客檔案、分群資訊
- SNS / Analytics 系 — SNS 貼文、觀眾、分析、銷售報告
- User 系（消費者） — 個人使用者的收據、支出、我的最愛店鋪等
如後述，User 系權限範圍原則上只授予第一方應用程式與已核准合夥人的嚴格權限範圍。
Store 系權限範圍
供店鋪業主、商業帳戶管理者以 OAuth 操作自家的店鋪資料的權限範圍。對外部合夥人應用程式也可授予，但需要店鋪端在 OAuth 同意畫面許可。
| 權限範圍 | 被授予的權限 |
|---|---|
store.products.read | 商品、庫存資訊的參照 |
store.products.write | 商品的登錄、更新 |
store.orders.read | 訂單資料的參照 |
store.orders.write | 訂單狀態的更新 |
store.customers.read | 顧客資料的參照 |
store.customers.write | 顧客的建立、更新、刪除 |
store.coupons.read | 優惠券資料的參照 |
store.coupons.write | 優惠券的建立、更新 |
store.inventory.read | 倉庫、庫存資料的參照 |
store.inventory.write | 庫存數的調整、盤點反映 |
store.flyers.read | 店鋪傳單的參照 |
store.flyers.write | 店鋪傳單的建立、更新、公開 |
store.staff.read | 員工、staff 資訊的參照 |
store.staff.write | 員工的建立、更新、刪除 |
store.business-hours.read | 營業時間、特例營業日、可就業時間的參照 |
store.business-hours.write | 營業時間、特例營業日、可就業時間的更新 |
store.reservations.read | 預約、預約框、座位資訊的參照 |
store.reservations.write | 預約的建立、變更、狀態更新，預約框的生成 |
store.info.read | 店鋪的基本資訊（店鋪名、聯絡處、地址）的參照 |
store.info.write | 店鋪的基本資訊（店鋪名、聯絡處、地址）的更新 |
CRM 系權限範圍
| 權限範圍 | 被授予的權限 |
|---|---|
crm.profiles.read | CRM 顧客檔案的參照 |
crm.segments.read | CRM 分群、排名的參照 |
SNS / Analytics 系權限範圍
| 權限範圍 | 被授予的權限 |
|---|---|
sns.content.read | SNS 貼文資料的參照 |
sns.content.write | SNS 貼文的建立、更新、公開、預約、刪除 |
sns.audience.read | SNS 觀眾資料的參照 |
analytics.read | 分析快照的參照 |
sales.read | 銷售報告、交易資料與商業洞察的參照 |
User 系（消費者）權限範圍
這些權限範圍是存取個人使用者的收據、支出、我的最愛店鋪等消費者個人資料的。只授予 ReceiptRoller 第一方應用程式，與明示地被核准的合夥人應用程式。
在未審查的應用程式指定
user.* 權限範圍呼叫授權 URL，會回傳 app_not_approved 錯誤。
| 權限範圍 | 被授予的權限 |
|---|---|
user.profile.read | 使用者基本資訊的參照 |
user.profile.write | 使用者基本資訊的更新 |
user.receipts.read | 使用者收到的收據的參照 |
user.spending.read | 月次支出摘要的參照 |
user.spending.write | 支出、預算資料的更新 |
user.coupons.read | 我的最愛店鋪的優惠券參照 |
user.favorites.read | 我的最愛店鋪一覽的參照 |
user.favorites.write | 我的最愛店鋪的追加、刪除 |
重要的制約
1. User 系權限範圍是事前審查制
OAuth 應用程式登錄時含 user.* 權限範圍，應用程式的 UserScopeStatus 會變成 pending（等待審查）。到 ReceiptRoller 營運團隊的審查變成 approved 為止，在授權流程指定 user.* 權限範圍會回傳錯誤。
外部的店鋪、合夥人「想在自家的 LIFF 應用程式或行動應用程式，顯示使用者收到的全收據」這樣的使用案例，原則上是這個審查的對象。請隨意向支援洽商。
2. Store 系與 User 系無法混在同一授權流程
1 個授權請求無法同時指定 store.orders.read 與 user.receipts.read。因為這些行為者（店鋪 vs. 使用者）不同，授權伺服器會拒絕。
要做處理兩者的資料的服務的情況，請登錄 2 個 OAuth 應用程式，以各自別別的授權流程取得權杖。
3. 最小權限的原則
為了獲得使用者（或店鋪業主）的信賴，也請只指定真的必要的權限範圍。「為了以防萬一也放入 write」「不使用但其他權限範圍也申請」不建議。
依使用案例的建議權限範圍
| 想做的事 | 必要的權限範圍 | 備考 |
|---|---|---|
| 從外部系統同步店鋪的庫存、訂單 | store.products.read store.products.write store.orders.read |
店鋪業主的同意可取得 |
| 反映庫存數的調整、盤點結果 | store.inventory.read store.inventory.write |
店鋪業主的同意可取得 |
| 從外部的預約系統、行動應用程式接受預約 | store.reservations.read store.reservations.write |
店鋪業主的同意可取得 |
| 在班表管理應用程式處理員工與可就業時間 | store.staff.read store.staff.write store.business-hours.read |
店鋪業主的同意可取得 |
| 從 staff 應用程式、外部系統更新店鋪資訊（店鋪名、聯絡處、地址） | store.info.read store.info.write |
店鋪業主的同意可取得。參照不需授予，更新需要 store.info.write |
| 將自家的店鋪傳單從公司內 CMS 批次投稿 | store.flyers.write |
店鋪業主的同意可取得 |
| 對行銷部門串接 CRM 分群 | crm.profiles.read crm.segments.read |
店鋪業主的同意可取得 |
| 將銷售儀表板組入自家工具 | sales.read analytics.read |
店鋪業主的同意可取得 |
| 在自家行動應用程式顯示使用者的全收據 | user.receipts.read |
需要事前審查 |
| 在記帳應用程式可視化月次支出 | user.spending.read user.receipts.read |
需要事前審查 |
| 想在 LIFF 取得他社的店鋪資料 | — | 不可（只能取得自家的 Store 系權限範圍） |
關於從 LIFF / LINE Mini App 的利用
從 LIFF 應用程式（LINE Mini App）呼叫 ReceiptRoller 的 API 的情況，也使用標準的 OAuth 2.0 Authorization Code 流程。
不提供 LINE ID 權杖的直接交換
「LINE ID 權杖 → ReceiptRoller 的存取權杖」直接交換的端點現時點不提供。LIFF 應用程式也與其他 Web 應用程式相同，需要誘導使用者到 ReceiptRoller 的授權畫面。
LIFF 的實作模式
- LIFF 應用程式啟動後，以
liff.init()初始化 LIFF - ReceiptRoller API 需要的時機，以
liff.openWindow()或通常的連結誘導到/oauth/authorize - 使用者在 ReceiptRoller 的授權畫面許可，
redirect_uri會回傳授權碼 - 將授權碼以
POST /api/v1/auth/token（grantType: authorization_code）交換為存取權杖 - 將取得的權杖以
Authorization: Bearer標頭附加至 API 請求
使用 User 系權限範圍時的注意
在 LIFF 應用程式指定 user.* 權限範圍的情況也需要上述的事前審查。「因為在 LINE 已驗證所以 ReceiptRoller 的使用者驗證可省略」這樣的設計不成立。這是為了安全性與使用者同意的透明性的設計。
相關指南
-
利用開始為止的流程說明 ReceiptRoller 的開發者入口利用開始為止的流程。作為店鋪使用者登錄，只要是 Starter 方案以上，無需另行的開發者申請即可立刻開始應用程式登錄與 API 實作。
-
什麼是應用程式登錄說明 ReceiptRoller 的應用程式登錄的概念。透過將應用程式登錄為 OAuth 用戶端，會發行用戶端 ID、密鑰、重新導向 URI，可開始 API、Webhook 串接。
-
新增建立應用程式說明在 ReceiptRoller 的開發者入口登錄新的應用程式（OAuth 用戶端）的具體步驟。涵蓋輸入項目、驗證、建立後的憑證顯示、常見錯誤。
-
錢包應用程式向：以 OAuth 取得使用者的收據的指南解說從 iOS、Android、LINE Mini App 等錢包型應用程式，在使用者同意下取得 ReceiptRoller 的購買收據的方法。涵蓋 OAuth 2.0 驗證、收據 API、Webhook 串接。