このガイドの目的

モバイルアプリやサーバーアプリから、レシートローラーのビジネスアカウント（旧称：組織）・店舗・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 — 1ページあたりの件数（既定 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スコープ一覧と利用可否
• アプリを新規作成する