店鋪向：以自家應用程式發行數位收據、以 Webhook 通知的指南

本指南說明登錄 ReceiptRoller 的開發者應用程式，以 OAuth 驗證取得存取權杖後，設定 Webhook，到即時接收收據事件為止的步驟。

主要的使用案例是 想以店鋪獨自的應用程式向顧客提供數位收據 的情況。可活用 ReceiptRoller 的基礎，同時以自家應用程式的品牌送達收據。

步驟 1：登錄開發者應用程式

1. 登入 ReceiptRoller，開啟對象的商業帳戶儀表板。
2. 從側選單選擇 開發者入口 → 應用程式一覽。
3. 點擊 建立應用程式 按鈕。
4. 輸入以下項目。
   • 應用程式名：自家服務的名字等
   • 重新導向 URI：接收 OAuth 授權碼的 URL（例：https://your-app.example.com/callback）
   • 權限範圍：選擇收據接收需要的權限範圍（參照下記）
5. 建立完成後，Client ID 與 Client Secret 會被發行。
   Client Secret 只顯示一次。請務必保存到安全的場所。

必要的權限範圍

店鋪對自家的顧客發行、參照收據的情況，需要以下的權限範圍。

※ user.receipts.read 或 user.profile.read 是顧客串接自身的 ReceiptRoller 帳戶的錢包型應用程式向。店鋪以自家發行收據的情況不需要。

步驟 2：以 OAuth 取得存取權杖

ReceiptRoller 採用 OAuth 2.0 授權碼流程（PKCE 對應）。

1. 授權請求

將使用者重新導向到以下的 URL：

GET /oauth/authorize
  ?client_id=app_xxxxxxxxxxxxxxxx
  &redirect_uri=https://your-app.example.com/callback
  &response_type=code
  &scope=store.orders.read store.orders.write store.products.read store.customers.read
  &code_challenge=<S256 雜湊>
  &code_challenge_method=S256

2. 授權碼的交換

使用者同意後，redirect_uri 會附帶 ?code=xxx 被重新導向。將這個碼與存取權杖交換：

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

{
  "grant_type": "authorization_code",
  "code": "xxx",
  "code_verifier": "<PKCE 碼驗證子>",
  "client_id": "app_xxxxxxxxxxxxxxxx",
  "client_secret": "your-client-secret",
  "redirect_uri": "https://your-app.example.com/callback"
}

3. 回應

{
  "access_token": "...",   // 有效期限：1小時
  "refresh_token": "...",  // 有效期限：30天
  "token_type": "Bearer",
  "expires_in": 3600
}

之後的 API 請求附加 Authorization: Bearer {access_token} 標頭發送。

步驟 3：登錄 Webhook

使用 Webhook，可在 ReceiptRoller 上事件（訂購建立等）發生時，對指定的 URL 即時接收通知。

從 UI 登錄的情況

1. 開啟開發者應用程式的詳細頁面。
2. 點擊 Webhooks 區段的 追加 按鈕。
3. 選擇 HTTPS 的 URL 與想接收的事件類型登錄。
4. 會顯示簽章密鑰 — 只顯示一次。請務必保存。

從 API 登錄的情況

POST /api/v1/webhooks
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "url": "https://your-app.example.com/hooks",
  "event_types": ["order.created", "order.updated"],
  "secret": "my-signing-secret"
}

登錄成功時的回應：

{
  "id": "wh_aBcDeFgHiJkLmNoP",
  "url": "https://your-app.example.com/hooks",
  "event_types": ["order.created", "order.updated"],
  "active": true,
  "created_at": "2026-04-14T09:00:00Z",
  "secret": "my-signing-secret"  // 這個值只回傳一次
}

可利用的事件類型

步驟 4：接收、驗證 Webhook

從 ReceiptRoller 發送的請求含有以下的標頭：

簽章的驗證方法（C# 的例子）

var secret = "my-signing-secret";
var rawBody = await Request.Body.ReadAllBytesAsync();
var expected = "sha256=" + Convert.ToHexStringLower(
    HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), rawBody));
var received = Request.Headers["X-RR-Signature"].ToString();

if (!CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(received)))
{
    return Unauthorized(); // 簽章不一致 → 不正的請求
}

酬載的形式

{
  "id": "evt_a1b2c3d4e5f6",
  "event": "order.created",
  "timestamp": "2026-04-14T09:00:00Z",
  "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "order_id": "ORD-20260414-ABCD",
    "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "Pending"
  }
}

回傳 2xx 狀態則視為投放成功。
投放失敗時在 1分後、10分後、1小時後最多自動重試 4 次。4 次失敗的情況 Webhook 會自動地被無效化。

步驟 5：測試連線

Webhook 登錄後，以測試發送可確認疏通：

POST /api/v1/webhooks/test/{webhook_id}
Authorization: Bearer {access_token}

回應範例：

{
  "webhook_id": "wh_aBcDeFgHiJkLmNoP",
  "http_status": 200,
  "success": true,
  "delivered_at": "2026-04-14T09:00:01Z"
}

投放紀錄的確認：

GET /api/v1/webhooks/{webhook_id}/deliveries
Authorization: Bearer {access_token}

彙整

1. 登錄開發者應用程式，取得 Client ID / Secret
2. 選擇必要的權限範圍以 OAuth 取得存取權杖
3. 登錄 Webhook 端點訂閱事件
4. 驗證接收到的 Webhook 的簽章並處理酬載
5. 以測試發送確認運作

不明之處請一併參照 API 文件（/swagger）。