取得商業帳戶、店鋪、POS 端末的一覽

本指南的目的

本文彙整從行動應用程式或伺服器應用程式，想一覽 ReceiptRoller 的商業帳戶、店鋪、POS 端末時的 API 使用方法。常見的使用情境如下。

• 在應用程式內讓使用者選擇「要以哪個商業帳戶操作」的畫面
• 一覽選擇後商業帳戶底下的店鋪，切換報表或操作對象的畫面
• 一覽選擇後店鋪的 POS 端末，選擇交易查詢或端末 QR 串接對象的畫面
• 1 位使用者跨多個商業帳戶存取的業務應用程式

前提

• 已在開發者儀表板完成應用程式憑證登錄
• 已透過 OAuth 2.0 授權碼流程取得與使用者關聯的存取權杖（支援多商業帳戶時，請在應用程式設定中將「授權時將權杖關聯至 1 個商業帳戶」的勾選關閉 — 詳情請參閱 原生行動應用程式指南）
• 基底 URL: https://receiptroller.io

1. 一覽使用者所屬的商業帳戶

首先，取得目前使用者作為成員的商業帳戶。

GET /api/v1/me/organizations
Authorization: Bearer {access_token}

查詢參數（選填）

• page — 頁碼（1 開始、預設 1）
• pageSize — 每頁的筆數（預設 100、最大 1000）

回應範例

{
  "organizations": [
    {
      "id": "a04507de-043a-4b47-b0a3-6204562f6e20",
      "name": "株式会社レシートローラー",
      "role": "Owner"
    },
    {
      "id": "7c2e0e9b-1f3a-4c6d-8a01-2b9f4d5e6c00",
      "name": "サンプル小売株式会社",
      "role": "Member"
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 2,
  "totalPages": 1
}

重點

• id 即為商業帳戶 ID（UUID）。在下一個請求中直接使用
• role 是該使用者的權限角色（Owner / Member / ProductManager 等）
• totalPages 為 2 以上時請推進 page 取得全部 — 在行動應用程式端不要只顯示第 1 頁就結束是重點

2. 一覽商業帳戶底下的店鋪

使用步驟 1 取得的 id，取得店鋪的一覽。

GET /api/v1/me/organizations/{organizationId}/stores
Authorization: Bearer {access_token}

查詢參數（選填）

• includeDeleted — 是否包含已刪除店鋪（預設 false）。通常不需要指定

回應範例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "role": "Owner",
  "stores": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "渋谷店",
      "storeType": "Retail",
      "primaryCategory": "コーヒーショップ",
      "status": "Active",
      "isDeleted": false,
      "isPosConnected": true,
      "address": {
        "country": "JP",
        "prefecture": "東京都",
        "city": "渋谷区",
        "line1": "宇田川町1-1",
        "line2": "",
        "postalCode": "150-0042",
        "latitude": 35.6595,
        "longitude": 139.7005
      },
      "phone": "03-1234-5678",
      "websiteUrl": "https://example.com/shibuya",
      "updatedAt": "2026-05-30T12:34:56Z"
    }
  ],
  "totalCount": 1
}

重點

• id 即為店鋪 ID。傳給 /api/v1/sales/* 等報表 API 作為 storeId
• 若呼叫來源的使用者非該商業帳戶的成員，會回傳 403 Forbidden
• 以 includeDeleted=true 也可包含已刪除店鋪，但一般的應用程式請勿加上（會誤將已歇業店鋪顯示出來）

3. 一覽店鋪底下的 POS 端末

使用步驟 2 取得的店鋪 id，取得登錄於該店鋪的 POS 端末。

GET /api/v1/me/organizations/{organizationId}/stores/{storeId}/pos-terminals
Authorization: Bearer {access_token}

查詢參數（選填）

• includeDeleted — 是否包含已刪除端末（預設 false）

回應範例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "terminals": [
    {
      "id": "term-001",
      "name": "レジ1（フロント）",
      "vendor": "Smaregi",
      "integrationType": "API",
      "location": "1F カウンター",
      "serialNumber": "SMG-2024-0001",
      "isActive": true,
      "publicTerminalId": "T-XYZ123",
      "transactionCount": 4821,
      "lastSyncAt": "2026-06-01T03:00:00Z",
      "lastSyncStatus": "Success",
      "lastTransactionAt": "2026-06-01T11:42:18Z",
      "updatedAt": "2026-06-01T03:00:00Z"
    }
  ],
  "totalCount": 1
}

安全性相關的注意

• POS 端末的供應商驗證資訊（apiKey / apiSecret / accessToken / refreshToken）絕對不會回傳。回應僅為運用中繼資料
• 若店鋪不屬於指定的商業帳戶，會回傳 404（防止以推測 ID 參照其他租戶）

4.（選填）整批取得整個商業帳戶的 POS 端末

想看「整個帳戶的 POS 同步進行到哪裡」等情況時，也可以一覽整個商業帳戶的 POS 端末。各端末會帶有 storeId 與 storeName，因此可依店鋪分組。

GET /api/v1/me/organizations/{organizationId}/pos-terminals
Authorization: Bearer {access_token}

回應範例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "role": "Owner",
  "terminals": [
    {
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "storeName": "渋谷店",
      "terminal": {
        "id": "term-001",
        "name": "レジ1（フロント）",
        "vendor": "Smaregi",
        "integrationType": "API",
        "isActive": true,
        "lastSyncAt": "2026-06-01T03:00:00Z",
        "lastSyncStatus": "Success"
      }
    }
  ],
  "totalCount": 1
}

要製作各店鋪的選擇 UI 時使用 section 3 的店鋪範圍版（/stores/{storeId}/pos-terminals），要在儀表板橫跨顯示時則使用這個端點，依情況區分使用。

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

1. 將以 OAuth 取得的存取權杖保存於安全儲存區（iOS Keychain / Android EncryptedSharedPreferences）
2. 應用程式啟動時呼叫 GET /api/v1/me/organizations，顯示於商業帳戶選擇 UI
3. 使用者選擇商業帳戶後，以 GET /api/v1/me/organizations/{organizationId}/stores 取得店鋪一覽
4. 店鋪被選擇後，以 GET /api/v1/me/organizations/{organizationId}/stores/{storeId}/pos-terminals 取得 POS 端末
5. 將選擇中的商業帳戶 ID／店鋪 ID／端末 ID 保存於本地，傳給之後的業務 API
6. 使用者選擇「切換」後，回到選擇 UI 重複相同流程

錯誤回應

相關資訊

• 原生行動應用程式指南：多商業帳戶存取與 OAuth 流程
• API 驗證指南（OAuth 2.0 授權碼流程）
• OAuth 權限範圍一覽與可用與否
• 建立新的應用程式