このガイドでは、レシートローラーのデベロッパーアプリを登録し、OAuth 認証でアクセストークンを取得した後、 Webhook を設定してリアルタイムにレシートイベントを受信するまでの手順を説明します。

主なユースケースは 店舗独自のアプリでお客様にデジタルレシートを提供したい 場合です。レシートローラーのインフラを活用しながら、自社アプリのブランドでレシートを届けることができます。

ステップ 1：デベロッパーアプリを登録する

1. レシートローラー にログインし、対象の組織ダッシュボードを開きます。
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 は、お客様が自身の Receipt Roller アカウントを連携するウォレット型アプリ向けです。店舗が自社でレシートを発行する場合は不要です。

ステップ 2：OAuth でアクセストークンを取得する

Receipt Roller は 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 を使うと、Receipt Roller でイベント（注文作成など）が発生した際に、指定した 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 を受信・検証する

Receipt Roller から送信されるリクエストには以下のヘッダーが含まれます：

署名の検証方法（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）もあわせてご参照ください。