このガイドの目的

レシートローラーの売上実績API（Sales API）を使って、ビジネスアカウント全体／特定店舗／特定POS端末の売上を取得する方法をまとめます。モバイルアプリやサーバー連携で「売上ダッシュボード」を作るときの入り口になるガイドです。

前提

• OAuth 2.0 認可コードフローでアクセストークンを取得済みであること
• アプリのスコープに sales.read を含めていること
• 事前にビジネスアカウントと店舗のIDを取得していること（ビジネスアカウント・店舗・POS端末の一覧を取得する）
• ベースURL: https://receiptroller.io

エンドポイント一覧

ビジネスアカウント全体の売上（KPI）

選択中のビジネスアカウントの「今月の数字」を取りたいときは、storeId を付けずに kpis を呼びます。

GET /api/v1/sales/kpis?organizationId={organizationId}
Authorization: Bearer {access_token}

レスポンス構造

すべての数値フィールドは KpiValue という共通の入れ子型で返ります。クライアント側で前月比や増減率を再計算する必要はありません。

{
  "organizationId": "0aa2...e7b1",
  "currentMonth": "2026-06",
  "previousMonth": "2026-05",

  "totalStores":       { "current": 12,       "previous": 12,       "changePercent": 0.0  },
  "totalStaff":        { "current": 87,       "previous": 84,       "changePercent": 3.6  },
  "totalProducts":     { "current": 1450,     "previous": 1410,     "changePercent": 2.8  },
  "totalCustomers":    { "current": 8920,     "previous": 8650,     "changePercent": 3.1  },
  "totalRevenue":      { "current": 3850000,  "previous": 3520000,  "changePercent": 9.4  },
  "totalTransactions": { "current": 1240,     "previous": 1180,     "changePercent": 5.1  },
  "averageTicket":     { "current": 3104.84,  "previous": 2983.05,  "changePercent": 4.1  },
  "avgGoogleRating":   { "current": 4.3,      "previous": 4.2,      "changePercent": 2.4  },
  "totalReservations": { "current": 210,      "previous": 195,      "changePercent": 7.7  }
}

KpiValue の中身

• current — 当月の値
• previous — 前月の値（前月のスナップショットが無いときは null）
• changePercent — 前月比の変化率（%）。previous が null または 0 のときは null

averageTicket について

• サーバー側で totalRevenue / totalTransactions を計算済みで返ります。クライアントで再計算する必要はありません
• 取引数が 0 のときは current: 0 を返します（NaN にはなりません）
• 店舗単位・POS端末単位でも同じ averageTicket フィールドが返ります

特定店舗の売上

同じエンドポイントに storeId を付けると、その店舗だけのKPIを返します。レスポンスは StoreDashboardKpis 形式（フィールド名は revenue, transactionCount, averageTicket など店舗向けの命名）です。

GET /api/v1/sales/kpis?organizationId={organizationId}&storeId={storeId}
Authorization: Bearer {access_token}

{
  "storeId": "store-001",
  "storeName": "渋谷本店",
  "currentMonth": "2026-06",

  "staffCount":       { "current": 12,      "previous": 11,      "changePercent": 9.1  },
  "revenue":          { "current": 850000,  "previous": 780000,  "changePercent": 8.9  },
  "transactionCount": { "current": 340,     "previous": 310,     "changePercent": 9.6  },
  "averageTicket":    { "current": 2500.0,  "previous": 2516.13, "changePercent": -0.6 },
  "reservationCount": { "current": 45,      "previous": 38,      "changePercent": 18.4 },
  "googleRating":     { "current": 4.4,     "previous": 4.3,     "changePercent": 2.3  },
  "productCount":     { "current": 320,     "previous": 318,     "changePercent": 0.6  },
  "customerCount":    { "current": 1820,    "previous": 1750,    "changePercent": 4.0  }
}

時系列トレンド

過去 N ヶ月の月次推移を取得します。グラフ描画に使います。

GET /api/v1/sales/trend?organizationId={organizationId}&storeId={storeId}&months=12
Authorization: Bearer {access_token}

ポイント

• months は最大 60。storeId を省略するとビジネスアカウント合算
• 現在は月次のみ。日次・週次のグラフが必要な場合は近日リリース予定です（?granularity=day|month の追加を計画中、追跡: t-e9a2f468）

商品別売上（期間指定）

「先月の売れ筋トップ50」など、自由な期間で商品別の売上を集計します。

GET /api/v1/sales/products
  ?organizationId={organizationId}
  &storeId={storeId}
  &since=2026-05-01
  &until=2026-05-31
  &sortBy=revenue
  &category=ドリンク
  &search=ラテ
  &terminalId={terminalId}     # （任意）特定POS端末だけの集計
Authorization: Bearer {access_token}

ポイント

• since / until は日付（含み始め、終わりは until の翌日 0:00 まで）
• レスポンスにはABCグループ（A：累積売上70%以下／B：90%以下／C：それ以降）、粗利・粗利率、合計粗利KPIが含まれます
• sortBy: revenue（既定）/ quantity / margin
• terminalId を付けるとその端末1台分の集計に絞れます（後述の「POS端末で絞り込む」を参照）

複数店舗を比較したい場合

ビジネスアカウントの複数店舗を1枚のグラフに重ねるときは multi-trend を使います。

GET /api/v1/sales/multi-trend
  ?organizationId={organizationId}
  &storeIds=store-001,store-002,store-003
  &months=12
Authorization: Bearer {access_token}

最大10店舗まで。6店舗を超えると線が読みづらくなるので、ユーザーが選択した店舗を対象にしぼると良いです。

来店分析（曜日・時間帯）

「平日朝7-9時に強い」「土曜午後に客足が増える」といった行動パターンを把握するためのエンドポイントです。

GET /api/v1/sales/visitors
  ?organizationId={organizationId}
  &storeId={storeId}
  &since=2026-05-01
  &until=2026-05-31
  &terminalId={terminalId}     # （任意）特定POS端末だけの集計
Authorization: Bearer {access_token}

レスポンスには時間帯別分布、曜日別分布、時間帯×曜日のヒートマップ、コンバージョン率（CRM紐付け率）、過去12ヶ月の新規／リピーター内訳が含まれます。

AIアドバイス（Intelligenceパネル）

売上の異常検知・予測・改善提案などのカードを取得します。

GET /api/v1/sales/advice
  ?organizationId={organizationId}
  &storeId={storeId}
  &severity=Action
  &category=Anomaly
Authorization: Bearer {access_token}

ポイント

• severity: Action / Warning / Opportunity / Info
• category: Trend / AverageTicket / MixShift / Anomaly / Forecast / Comparison
• カードは1日1回バッチで生成されます（リアルタイムではありません）

POS端末で絞り込む（terminalId）

「レジ1台だけの売上」「決まったキャスト・スタッフが入っていた端末の売上」のような POS端末（terminalId）レベルの絞り込みは、4つのエンドポイント（kpis、trend、products、visitors）でサポートしています。

# KPI（端末1台分の今月の数字 + MoM比較、averageTicket込み）
GET /api/v1/sales/kpis?organizationId={orgId}&storeId={storeId}&terminalId={terminalId}

# 月次トレンド（端末1台分の過去Nヶ月）
GET /api/v1/sales/trend?organizationId={orgId}&storeId={storeId}&terminalId={terminalId}&months=12

# 商品別売上（端末1台分の期間集計）
GET /api/v1/sales/products?organizationId={orgId}&storeId={storeId}&terminalId={terminalId}&since=...&until=...

# 来店分析（端末1台分の時間帯・曜日）
GET /api/v1/sales/visitors?organizationId={orgId}&storeId={storeId}&terminalId={terminalId}&since=...&until=...

ポイント

• terminalId を使う場合は storeId も必須です
• terminalId が指定した storeId に属さない場合は 404 が返ります（クロスストア参照防止）
• 端末IDは GET /api/v1/me/organizations/{orgId}/stores/{storeId}/pos-terminals で取得できます

端末単位での集計について

• /kpis と /trend は端末粒度のリクエスト時にライブ集計するため、応答に含まれるのは Revenue（売上）・TransactionCount（取引数）・AverageTicket（平均客単価）のみです。スタッフ数・商品数・Google評価などは端末単位の概念ではないため 0 が入ります
• /products と /visitors は元々ライブ集計のため、すべてのフィールドが端末粒度で正しく返ります

典型的なフロー（モバイルアプリ）

1. GET /api/v1/me/organizations でビジネスアカウントを取得
2. ユーザーが選んだら GET /api/v1/me/organizations/{orgId}/stores で店舗一覧
3. ダッシュボード画面で GET /api/v1/sales/kpis と GET /api/v1/sales/trend を並行リクエスト
4. ユーザーが店舗を切り替えたら同じエンドポイントを storeId 付きで再取得
5. 「POS端末別」タブを開いたら GET /api/v1/me/organizations/{orgId}/stores/{storeId}/pos-terminals で端末一覧を取得し、選ばれた端末で各 sales エンドポイントを terminalId 付きで再取得
6. 「商品別」タブを開いたら GET /api/v1/sales/products を呼ぶ
7. 「アドバイス」タブを開いたら GET /api/v1/sales/advice を呼ぶ

権限とトークン

• 必要スコープ: sales.read
• マルチビジネスアカウント対応のアプリは、ユーザースコープのアクセストークンで ?organizationId= を毎回明示
• 1ビジネスアカウントに固定するアプリは、認可時にビジネスアカウントを紐付けたトークンを使えば organizationId 省略可
• アクセストークン有効期限: 8時間。一日の業務シフトに合わせて長めに設定しています。ビジネスアカウントや店舗を切り替えても、同じトークンを使い回せます
• リフレッシュトークン有効期限: 30日。期限切れ時は POST /api/v1/auth/refresh で新しいアクセストークンを取得してください

エラーレスポンス

関連情報

• ビジネスアカウント・店舗・POS端末の一覧を取得する
• ネイティブモバイルアプリ向け：複数ビジネスアカウントアクセスとOAuthフロー
• API認証ガイド（OAuth 2.0 認可コードフロー）
• OAuthスコープ一覧と利用可否