交易一覽 API（Transactions API：POS＋OMS 整合摘要）的使用方式

本指南的目的

ReceiptRoller 的交易一覽 API（Transactions API）是將收銀營業額（POS 交易）與銷售管理上的訂單（OMS）整合為單一摘要的唯讀端點。涵蓋「想在 1 個畫面看到整個商業帳戶的交易」這個使用情境。

為何是獨立的端點

• Sales API（營業額實績 API） 會彙總 POS 交易並回傳 KPI／圖表
• Orders API（銷售管理 API） 提供 OMS 訂單的 CRUD
• 兩者都只看得到單方的世界。若需要「所有通路的交易一覽」，請使用本 API

注意: Transactions API 為唯讀。寫入請透過 Orders API（OMS）或各 POS 串接進行。

端點

GET /api/v1/transactions
  ?organizationId={organizationId}
  &storeId={storeId}                 (選填、以店鋪篩選)
  &since=2026-05-01T00:00:00Z        (選填、預設: 30 天前)
  &until=2026-06-01T00:00:00Z        (選填、預設: 現在)
  &source=all|pos|oms                (選填、預設: all)
  &page=1
  &pageSize=100                      (最大 500)
Authorization: Bearer {access_token}

必要權限範圍: store.orders.read 或 sales.read 其中之一。

回應範例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "window": {
    "since": "2026-05-01T00:00:00Z",
    "until": "2026-06-01T00:00:00Z"
  },
  "transactions": [
    {
      "id": "pos:term-001:tx-9001",
      "source": "pos",
      "occurredAt": "2026-05-31T18:22:14Z",
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "POS",
      "status": "Completed",
      "amounts": { "subtotal": 960, "tax": 96, "shipping": 0, "discount": 0, "total": 1056 },
      "itemCount": 2,
      "customer": null,
      "links": {
        "posTransactionId": "tx-9001",
        "posTerminalId": "term-001",
        "omsOrderId": null
      }
    },
    {
      "id": "oms:ord-001",
      "source": "oms",
      "occurredAt": "2026-05-31T09:10:00Z",
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "Web",
      "status": "Delivered",
      "amounts": { "subtotal": 1140, "tax": 114, "shipping": 500, "discount": 0, "total": 1754 },
      "itemCount": 3,
      "customer": { "name": "佐藤花子", "email": "hanako@example.com" },
      "links": {
        "posTransactionId": null,
        "posTerminalId": null,
        "omsOrderId": "ord-001"
      }
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 247,
  "totalPages": 3
}

欄位的解讀方式

• source — "pos" 或 "oms"。表示交易來自哪個世界
• occurredAt — POS 為交易日期時間，OMS 為建立日期時間。混合後以 DESC 順序排序
• channel — POS 恆為 "POS"。OMS 為 Web / Phone / Manual / Marketplace 等
• status — POS 為 Completed / Voided。OMS 為 Pending / Confirmed / Processing / Shipped / Delivered / Cancelled / Refunded
• customer — POS 為 null，OMS 若有輸入則為姓名、電子郵件
• links — 想以後續動作取得詳細時使用的 ID。POS 列會填入 posTransactionId + posTerminalId，OMS 列會填入 omsOrderId 回傳

限制事項

• 取得期間最大 365 天。超過時 400 Bad Request
• 每個來源在內部最多取得 5000 筆後合併。超過此值的長期間、大量交易的租戶，請以 since / until 篩選
• 每頁最多 500 筆
• POS 與 OMS 的關聯（例如在店鋪櫃台接收線上訂單等）尚未支援。此項預定於 t-e9a2f470（Phase 2）發布

POS 與 OMS 為不同世界的前提

目前的 ReceiptRoller 中：

• 收銀（Square / Smaregi / Air 收銀等）的收銀營業額 → 只寫入 PosTransactions
• Web 接單／電話接單／市集平台 → 只寫入 OmsOrders
• POS 與 OMS 目前並未連動。即使是同一商業帳戶的交易，也會分別記錄在兩個地方

本 API 是在 API 層將此分斷虛擬地整合。資料層的整合預定於今後的功能：

• Phase 2 (t-e9a2f470): 以 OmsOrder.LinkedPosTransactionId 連動線上訂單的店鋪接收
• Phase 3 (t-e9a2f471, t-e9a2f472): 將 POS 交易也自動 materialize 至 OMS。分析也統一至 OMS 基礎

典型的流程（行動應用程式）

1. 以 OAuth 取得存取權杖 → 權限範圍包含 store.orders.read 或 sales.read
2. 以 GET /api/v1/me/organizations 選擇商業帳戶
3. 在交易一覽畫面呼叫 GET /api/v1/transactions?since=...&pageSize=50，以無限捲動推進 page
4. 依各列的 source 切換顯示 POS 圖示／OMS 圖示
5. 點擊後查看 links，POS 列則跳轉至 /api/v1/sales/products 或 Sales API，OMS 列則跳轉至 GET /api/v1/orders/{omsOrderId}

錯誤回應

相關資訊

• 營業額實績 API（Sales API）的使用方式
• 銷售管理 API（Orders / OMS API）的使用方式
• 取得商業帳戶、店鋪、POS 端末的一覽
• OAuth 權限範圍一覽與可用與否