วิธีใช้ API จัดการสินค้า (Products API)

วัตถุประสงค์ของคู่มือนี้

คู่มือนี้สรุปวิธีสร้าง ดึงข้อมูล อัปเดต และลบมาสเตอร์สินค้าภายใต้บัญชีธุรกิจ โดยใช้API จัดการสินค้า (Products API)ของ ReceiptRoller เป็นคู่มือที่เป็นจุดเริ่มต้นเมื่อต้องการจัดการข้อมูลสินค้าจากแอปมือถือหรือการเชื่อมต่อฝั่งเซิร์ฟเวอร์

ข้อกำหนดเบื้องต้น

• ได้รับ access token ผ่าน OAuth 2.0 authorization code flow เรียบร้อยแล้ว
• สโคปของแอปมี store.products.read（อ่าน）／store.products.write（สร้าง・อัปเดต・ลบ）
• ทราบ ID ของบัญชีธุรกิจ（UUID）แล้ว（ดึงรายการบัญชีธุรกิจ・ร้านค้า・เครื่อง POS）
• Base 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）ซึ่งเพิ่งถูกออก…