วิธีใช้ Inventory / WMS API

เมื่อใช้ Inventory / WMS API คุณสามารถดูและปรับสต็อกของบัญชีธุรกิจแยกตามโลเคชัน (คลังสินค้า・หลังร้าน・พื้นที่ขาย) ได้ หากมีการแมปกับโลเคชันของ Shopify ไว้ การปรับสต็อกจาก API จะสะท้อนไปยัง Shopify โดยอัตโนมัติด้วย

ขอบเขตที่จำเป็น

• store.inventory.read — ดึงสต็อก・โลเคชัน・ประวัติการเคลื่อนไหว
• store.inventory.write — ปรับสต็อก

กรุณาร้องขอสโคปตอนลงทะเบียนแอปพลิเคชัน และขอความยินยอมจากเจ้าของธุรกิจ สำหรับโฟลว์การยืนยันตัวตน กรุณาดู คู่มือการยืนยันตัวตน API

รายการเอนด์พอยต์

• GET /api/v1/inventory — รายการสต็อก (กรองด้วย locationId / productId / lowStock=true)
• GET /api/v1/inventory/{locationId}/{productId} — รายละเอียดสต็อก
• GET /api/v1/inventory/locations — รายการโลเคชัน
• POST /api/v1/inventory/adjust — ปรับสต็อก
• GET /api/v1/inventory/movements — ประวัติการเคลื่อนไหวของสต็อก

การดูสต็อก

รายการสต็อกจะคืนมา 1 แถวต่อโลเคชัน×สินค้า เมื่อแนบ lowStock=true จะกรองเฉพาะแถวที่ต่ำกว่าจุดสั่งซื้อ (จำนวนสต็อกขั้นต่ำ) เท่านั้น

GET /api/v1/inventory?organizationId={orgId}&lowStock=true
Authorization: Bearer {access_token}

{
  "count": 2,
  "stock": [
    {
      "locationId": "loc-001",
      "locationName": "本店バックヤード",
      "productId": "prd-001",
      "productName": "有機マンゴージュース",
      "sku": "MNG-001",
      "quantity": 3,
      "availableQuantity": 3,
      "minStockLevel": 10,
      "isLowStock": true
    }
  ]
}

การปรับสต็อก

ระบุการเปลี่ยนแปลงจำนวนแบบมีเครื่องหมายและเหตุผล ค่าบวกคือรับเข้า ค่าลบคือเบิกออก・ทิ้ง การปรับจะถูกบันทึกในประวัติการเคลื่อนไหว โดยเก็บชื่อผู้รับผิดชอบและเหตุผลไว้

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

{
  "locationId": "loc-001",
  "productId": "prd-001",
  "quantityChange": -3,
  "reason": "破損廃棄"
}

หากแถวสต็อกเป้าหมายไม่มีอยู่ จะคืนค่า 404 แถวสต็อกจะถูกสร้างขึ้นเมื่อสินค้าถูกลงทะเบียนในโลเคชันเป็นครั้งแรกจากการประมวลผลรับเข้าหรือการตรวจนับสต็อก

การสะท้อนอัตโนมัติเมื่อเชื่อมต่อ Shopify

หากบัญชีธุรกิจเชื่อมต่อกับ Shopify และโลเคชันเป้าหมายถูกแมปกับโลเคชันของ Shopify ไว้ การปรับสต็อกจาก API จะสะท้อนไปยังฝั่ง Shopify โดยอัตโนมัติ ไม่จำเป็นต้องเรียก API เพิ่มเติม ทิศทางย้อนกลับ (การเปลี่ยนแปลงสต็อกฝั่ง Shopify) ก็จะสะท้อนมายัง ReceiptRoller ผ่าน Webhook เช่นกัน

การดึงประวัติการเคลื่อนไหว

สามารถดึงประวัติการรับเข้า・การเคลื่อนย้าย・การตรวจนับสต็อก・การปรับ (รวมถึงที่มาจากการซิงก์ Shopify) โดยเรียงจากใหม่ไปเก่าได้

GET /api/v1/inventory/movements?organizationId={orgId}&productId=prd-001
Authorization: Bearer {access_token}

การใช้งานผ่าน MCP tool

จาก AI เอเจนต์ เช่น ChatGPT หรือ Claude คุณสามารถใช้ฟังก์ชันเดียวกันผ่าน MCP server (https://mcp.receiptroller.io) ได้

• wms_get_stock — ดูสต็อก (รองรับฟิลเตอร์ lowStock)
• wms_list_locations — รายการโลเคชัน
• wms_adjust_stock — ปรับสต็อก
• wms_list_movements — ประวัติการเคลื่อนไหว

tool สำหรับสินค้า (pim_*)・คำสั่งซื้อ (oms_*) ก็ให้บริการบน MCP server เดียวกัน สำหรับวิธีเชื่อมต่อ MCP กรุณาดู การเชื่อมต่อ AI เอเจนต์ (MCP)

เพจที่เกี่ยวข้อง

• วิธีใช้ Products API
• วิธีใช้ Orders / OMS API
• เอกสารอ้างอิง Inventory API
• รหัสข้อผิดพลาดและแนวทางการ retry