購買・レシートデータ連携

レシートローラーで最も中心にあるデータがレシート（receipt）です。1回の決済が1レシートに対応し、複数の明細（item）を持ちます。POSや自社決済システムから発行され、店舗系・User系の両方のスコープでアクセスできます。

主なフィールド

関連スコープ

• receipt.read — 店舗のレシート読み取り
• receipt.write — レシートの新規発行・取消
• user.receipts.read — 一般消費者本人のレシート（要審査）
• user.receipts.write — 本人のレシートにメモ・タグ追加（要審査）

取得パターン

店舗オーナーとして取得

GET /v1/receipts?store_id=str_abc123&issued_after=2026-04-01
Authorization: Bearer {店舗トークン}

消費者本人として取得

GET /v1/me/receipts?limit=20
Authorization: Bearer {ユーザートークン}

レシートQRの発行（claim-token）

受け取りそびれたレシートを、その場で QR コードとして渡せます。ネイティブアプリ（Android / iOS）でレシートを表示したあと、対象取引の id から claim-token（ワンタイムの受け取りトークン）を発行し、返ってきた URL を QR にエンコードして画面に表示してください。お客様がスキャンすると、その 1 件のレシートを受け取れます（Web の POS 画面が出す QR と同じ仕組みです）。

1. claim-token を発行する

POST /api/v1/transactions/{id}/claim-token?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{ "ttlMinutes": 1440 }

{id} は取引一覧／詳細が返す合成 ID（pos:{terminalId}:{transactionId}）です。POS 取引のみ対応します（OMS 注文は 400）。スコープは store.orders.read または sales.read。ttlMinutes は任意（既定 1440 = 24 時間）。

レスポンス

{
  "id": "pos:9edfb4b8-...:6a8c44a6-...",
  "claimToken": "a7K3xQ9mZp2v",
  "claimUrl": "https://receiptroller.io/rx/a7K3xQ9mZp2v",
  "expiresAt": "2026-06-22T06:40:00Z"
}

2. QR を生成する — claimUrl をそのまま QR ライブラリ（Android は ZXing など）でエンコードして表示します。QR にはレシートデータ自体は含まれず、URL のみが入ります。画像はアプリ側で生成するため、サーバーへの画像リクエストは不要です。

• トークンは単回使用・既定 24 時間で失効します（ttlMinutes で変更可）。スキャンされなかった場合は再度発行してください。
• お客様がスキャンすると https://receiptroller.io/rx/{claimToken} に着地し、ネイティブアプリ（ユニバーサルリンク／アプリリンク）または Web プレビューがその取引のレシートを表示します。
• 店舗端末に固定で貼る QR（レジ単位・最新取引を表示）が必要な場合は、端末の publicTerminalId から https://receiptroller.io/r/{publicTerminalId} をエンコードしてください。

Webhookイベント

• receipt.issued — 発行
• receipt.voided — 取消
• receipt.refunded — 返金
• receipt.updated — 内容更新（補足追加など）

よくあるユースケース

• 会計連携：日次でレシートを取得して会計ソフトに登録
• 消費者向けレシート管理アプリ：本人レシートを家計簿アプリに同期
• レシートQRの受け渡し：レジ後にアプリでQRを表示し、お客様が電子レシートを受け取る
• BI集計：時間帯別・商品別の売上分析（明細単位の税・割引も活用）
• 不正検知：返金率の異常値検知

注意点

• 明細を含むレシートはペイロードが大きいため、一覧取得時は明細を含めない（?expand=items で明示時のみ含む）
• 取消・返金された場合、元レシートは残り status が変わる。集計時は status を必ず参照
• 金額は税込・税抜の両方が total_amount / subtotal として提供される
• 明細単位の税額・割引額、決済テンダーの内訳（分割会計）、返金内訳、カードブランド/下4桁は、ソース POS が送る場合に保持される（取りこぼし防止のため生ペイロードもサーバー側に保管）
• レシートQR（claim-token）の payload は URL のみ。レシートデータは /rx/{token} 着地後に取得されるため、QR 自体に個人情報は含まれません

関連ガイド

• PosTransactionDto リファレンス — POS から取り込まれた取引の内部モデル仕様
• ウォレットアプリ向けレシート取得ガイド
• 店舗向けレシート発行・Webhookガイド
• OAuthスコープ一覧
• 開発者ヘルプトップへ戻る