このガイドの目的

レシートローラーの商品管理API（Products API）を使って、ビジネスアカウント配下の商品マスターを作成・取得・更新・削除する方法をまとめます。モバイルアプリやサーバー連携から商品データを操作するときの入口になるガイドです。

前提

• OAuth 2.0 認可コードフローでアクセストークンを取得済みであること
• アプリのスコープに store.products.read（読み取り）／store.products.write（作成・更新・削除）を含めていること
• ビジネスアカウントID（UUID）が分かっていること（ビジネスアカウント・店舗・POS端末の一覧を取得する）
• ベースURL: https://receiptroller.io

エンドポイント一覧

1. 商品一覧を取得する

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

クエリパラメータ（任意）

• search — 商品名・SKU・JANコードの部分一致検索
• category — カテゴリで絞り込み（完全一致）
• brand — ブランドで絞り込み（完全一致）

レスポンス例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "products": [
    {
      "id": "prd-001",
      "productName": "ブレンドコーヒー M",
      "sku": "CFE-BLD-M",
      "janCode": "4912345000017",
      "category": "ドリンク",
      "brand": "オリジナル",
      "pricing": {
        "basePrice": 480,
        "baseCostPrice": 120,
        "taxRate": 0.10,
        "storePrices": []
      },
      "images": {
        "cover": "https://...",
        "gallery": ["https://..."]
      },
      "status": "Active",
      "variants": { "hasVariants": false, "options": [], "items": [] },
      "integrations": {
        "squareCatalogObjectId": "",
        "smaregiProductId": "SMG-12345"
      },
      "createdAt": "2026-04-01T09:00:00Z",
      "updatedAt": "2026-05-30T12:34:56Z"
    }
  ],
  "totalCount": 1
}

2. 1商品の詳細を取得する

GET /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}

バリアント（サイズ・色違いなど）も含めて返ります。商品が指定ビジネスアカウントに属さない場合は 404。

3. 商品を新規作成する

POST /api/v1/products?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "productName": "新商品 アイスティー",
  "sku": "TEA-ICE-001",
  "janCode": "4912345000024",
  "category": "ドリンク",
  "brand": "オリジナル",
  "description": "夏季限定の冷茶。",
  "basePrice": 380,
  "baseCostPrice": 95,
  "taxRate": 0.10,
  "status": "Active",
  "imageUrl": "https://..."
}

ポイント

• productName のみ必須。それ以外は省略可
• リクエストボディに organizationId を含めても無視されます。トークン／クエリで解決したビジネスアカウントが必ず使われます（他テナントへの誤書き込み防止）
• レスポンスは新しく採番された id（productId）を含む完全な商品オブジェクト

4. 商品を更新する

PUT /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "productName": "新商品 アイスティー（無糖）",
  "basePrice": 400,
  "status": "Active"
}

送ったフィールドで商品レコードを上書きします（部分更新ではなく完全置換）。値を保持したいフィールドは既存値を一緒に送り直してください。

5. 商品を削除する（ソフトデリート）

DELETE /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}

ポイント

• レスポンスは 204 No Content
• ソフトデリートのため、過去のPOSレシート明細から該当商品IDの解決は引き続き可能
• 削除済み商品は一覧・検索結果には含まれません

POS連携IDの扱い

レシートローラーの商品マスターは外部POSと連携しています。integrations ブロックに以下のIDが入る場合があります。

• squareCatalogObjectId / squareVariationId — Square Catalog との紐付け
• smaregiProductId — スマレジの商品IDとの紐付け

外部POS主導で同期している商品は、これらのIDが自動的にセットされます。APIから直接書き込むこともできますが、通常はPOS同期に任せて触らない方が安全です。

バリアント（サイズ・色違い）

1商品に複数のバリアントがある場合、variants.hasVariants = true となり variants.options（オプション定義）と variants.items（各バリアントの実体）が入ります。新規作成時は最低限の親商品だけ登録し、バリアントは別途UI／API追加で展開する設計が一般的です。

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

1. OAuthでアクセストークン取得 → スコープに store.products.read と store.products.write を含める
2. GET /api/v1/me/organizations でビジネスアカウントを選択
3. 商品一覧画面で GET /api/v1/products をページング表示
4. 新商品追加画面で POST /api/v1/products
5. 編集画面で GET /api/v1/products/{id} → PUT /api/v1/products/{id}
6. 削除確認後 DELETE /api/v1/products/{id}

エラーレスポンス

関連情報

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