このガイドの目的

レシートローラーの取引一覧API（Transactions API）は、レジでの売上（POSトランザクション）と販売管理上の注文（OMS）を1つのフィードに統合した読み取り専用のエンドポイントです。「ビジネスアカウント全体の取引を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 のいずれか1つ。

レスポンス例

{
  "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 で絞り込んでください
• 1ページあたり最大500件
• POSとOMSの紐付け（オンライン注文を店舗カウンターで受け取りなど）は未対応です。これは t-e9a2f470（Phase 2）でリリース予定です

POSとOMSは別の世界という前提

現状のレシートローラーでは：

• レジ（Square / スマレジ / Airレジなど）でのレジ売上 → PosTransactions のみに書き込まれます
• Web受注／電話受注／マーケットプレイス → OmsOrders のみに書き込まれます
• POSとOMSは現在連動していません。同じビジネスの取引なのに2つの場所に分かれて記録されます

本APIはこの分断をAPI層で仮想的に統合するものです。データ層の統合は今後のフェーズで予定しています：

• Phase 2 (t-e9a2f470): オンライン注文の店舗受け取りを OmsOrder.LinkedPosTransactionId で連動
• Phase 3 (t-e9a2f471, t-e9a2f472): POS取引をOMSにも自動materialize。分析も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スコープ一覧と利用可否