營業額實績 API（Sales API）的使用方式

本指南的目的

本文彙整使用 ReceiptRoller 的營業額實績 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）

各商品營業額（指定期間）

可以「上月的暢銷 Top 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 次批次產生（並非即時）

以 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 取得端末一覽，並以帶 terminalId 重新取得各 sales 端點
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 權限範圍一覽與可用與否