商品管理 API（Products API）的使用方式

本指南的目的

本文彙整使用 ReceiptRoller 的商品管理 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 的處理

ReceiptRoller 的商品主檔與外部 POS 串接。integrations 區塊中可能會有以下 ID。

• squareCatalogObjectId / squareVariationId — 與 Square Catalog 的關聯
• smaregiProductId — 與 Smaregi 商品 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 權限範圍一覽與可用與否