購買、收據資料串接

收據購買資料串接 API

本文的對象
適用於想串接 ReceiptRoller 核心資料——購買、收據資訊的開發者。

ReceiptRoller 最核心的資料是收據（receipt）。1 次結帳對應 1 收據，持有多個明細（item）。由 POS 或自家結帳系統發行，可從店鋪系、User 系兩方的權限範圍存取。

內部模型的正式規格在另一篇文章
本文處理概念與整合模式。關於實際從 POS 匯入的交易資料的 C# 模型（PosTransactionDto）的欄位定義，請參閱 PosTransactionDto 參考。

交易模型已擴充
為不遺漏來源 POS 送出的資料，已擴充交易模型。1 筆交易中，可取得明細（商品名、數量、單價、明細單位的稅額/折扣額、目錄 ID）、分割 tender 的付款內容明細（現金＋卡片等，各 tender 的金額、卡片品牌/末 4 碼）、退款內容明細、貨幣、收據 URL、外部串接 ID 等。欄位的詳細請參閱 PosTransactionDto 參考。

主要欄位

欄位	內容
`id`	收據ID（`rcp_`）
`store_id`	發行店鋪
`issued_at`	發行時刻
`total_amount`	合計金額（最小貨幣單位）
`tax_amount`	消費稅額
`currency`	貨幣碼
`payment_method`	付款方式（cash / credit_card / qr / etc）。分割結帳時也保留各 tender 的內容明細
`status`	issued / voided / refunded
`customer_id`	關聯顧客（選填）
`items[]`	明細陣列（商品名、數量、單價之外，也包含明細單位的稅額、折扣額）

取得模式

作為店鋪擁有者取得

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}，原生應用程式（Universal Link／App Link）或 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 提供
明細單位的稅額、折扣額、結帳 tender 的內容明細（分割結帳）、退款內容明細、卡片品牌/末 4 碼，會在來源 POS 送出時保留（為防止遺漏，原始承載也保存於伺服器端）
收據 QR（claim-token）的 payload 僅為 URL。收據資料在 /rx/{token} 著地後才取得，因此 QR 本身不含個人資訊