วิธีอัปโหลดแค็ตตาล็อกของคุณสำหรับ SiteChat

หากคุณใช้ SiteChat บนเว็บไซต์ของคุณเอง (ไม่ใช่ร้านค้า Shopify) คุณสามารถส่งระเบียนสินค้าที่มีโครงสร้างไปยัง Shoply เพื่อให้ผู้ซื้อค้นหาสินค้าเหล่านั้นได้ในแชต SiteChat และการค้นหาสินค้า

เอ็นด์พอยต์เหล่านี้ใช้ Settings → Store owner API secret เดียวกันกับส่วนอื่น ๆ ของ Shoply Merchant API และหน้า Product Catalog ในแอดมิน SiteChat สามารถเรียกใช้เอ็นด์พอยต์เหล่านี้ได้ด้วย admin access token ของคุณขณะลงชื่อเข้าใช้ ร้านค้า Shopify ยังคงซิงก์ข้อมูลแค็ตตาล็อกผ่าน Shopify ต่อไป เส้นทางอัปโหลดเหล่านี้มีให้ใช้เฉพาะบัญชี SiteChat ที่ยังไม่ได้ซิงก์แค็ตตาล็อกจาก Magento เท่านั้น

ในแอดมิน SiteChat เมนู Product Catalog จะเปิดพื้นที่ในลักษณะเดียวกับ Shopify ซึ่งมี Products, Collections และ Inventory คุณสามารถเพิ่มหรือแก้ไขสินค้า นำเข้า CSV/Excel จัดกลุ่มสินค้าเป็น manual collections และปรับจำนวนสต็อกได้

มี API อะไรให้ใช้งานบ้าง?

เมื่อบันทึกสินค้าสำเร็จ Shoply จะขอให้สร้างดัชนีร้านใหม่ จนกว่าการสร้างใหม่นั้นจะเสร็จสิ้น การตอบกลับจะรายงาน index_status: "pending" จากนั้นสินค้าที่เผยแพร่แล้วจะปรากฏทั้งในดัชนีสินค้าและในฐานความรู้ที่ SiteChat chat ใช้

ใครบ้างที่ใช้ API เหล่านี้ได้?

• ร้านค้าของคุณต้องเป็นบัญชี SiteChat (app_platform เป็น SiteChat)
• คีย์ของร้านค้า Shopify (รวมถึงโดเมน *.myshopify.com) จะถูกปฏิเสธ
• การยืนยันตัวตนต้องใช้ store-owner API secret ที่ถูกต้อง หรือ SiteChat admin access token สำหรับ store_key เดียวกับที่อยู่ในคำขอเท่านั้น
• Shopify Admin API token ไม่สามารถเรียกเส้นทางเหล่านี้ได้

สร้างหรือหมุนเวียน owner secret ได้แบบเดียวกับการเชื่อมต่อ Merchant API อื่น ๆ: วิธีใช้ Shoply Merchant API ในคอนโซลแอดมินของ SiteChat ให้เปิด Product Catalog เพื่อจัดการสินค้า คอลเลกชัน และสต็อก—หรือนำเข้าไฟล์ CSV หรือ Excel—โดยไม่ต้องจัดการ secret ด้วยตนเอง

การยืนยันตัวตนทำงานอย่างไร?

จากตัวเชื่อมต่อฝั่งเซิร์ฟเวอร์

เรียก API จากแบ็กเอนด์ที่เชื่อถือได้ผ่าน HTTPS ใส่สตริง JSON ลงในเฮดเดอร์ Authorization:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete คือชื่อฟิลด์สาธารณะ ซึ่งรวมการสะกดแบบเดิมตามประวัติไว้ด้วย store_owner_api_secret ก็ยอมรับเช่นกัน นี่ไม่ใช่โทเค็น Bearer

จากแอดมิน SiteChat

หน้า Product Catalog จะส่งเซสชันแอดมินที่คุณลงชื่อเข้าใช้แทน:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "admin_auth_token": "YOUR_SITECHAT_ACCESS_TOKEN"
}

access_token ใช้เป็นชื่อแทนของ admin_auth_token ได้

พารามิเตอร์ query store_key ต้องตรงกับเฮดเดอร์ เก็บ owner secret ไว้เฉพาะในตัวแปรสภาพแวดล้อมฝั่งเซิร์ฟเวอร์เท่านั้น—ห้ามใส่ในสคริปต์หน้าร้าน URL หรือรีโพสาธารณะโดยเด็ดขาด

export SHOPLY_STORE_KEY="your-sitechat-store-key"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

ฉันจะอัปโหลดสินค้าได้อย่างไร?

POST https://api.shoplyai.ai/merchant/products/batch?store_key=YOUR_SITECHAT_STORE_KEY

{
  "source": "woocommerce-main",
  "products": [
    {
      "external_id": "123",
      "title": "Trail shoes",
      "description": "Water-resistant hiking shoes.",
      "url": "https://example.com/products/trail-shoes",
      "currency": "USD",
      "price": "49.95",
      "original_price": "59.95",
      "available": true,
      "status": "published",
      "images": ["https://example.com/images/trail-shoes.jpg"],
      "categories": ["Footwear"],
      "metafields": {"material": "Leather"},
      "variants": [
        {
          "external_id": "124",
          "title": "Brown / 42",
          "sku": "TRAIL-BR-42",
          "price": "49.95",
          "available": true,
          "metafields": {"color": "Brown", "size": "42"}
        }
      ]
    }
  ]
}

ฟิลด์และกฎที่จำเป็น

• ฟิลด์สินค้าที่จำเป็น: external_id, title, url, currency, price และ available โดยค่าเริ่มต้นของ status คือ published
• สต็อกแบบเลือกได้: ตั้ง tracks_inventory เป็น true และกำหนด quantity ที่ไม่ติดลบบนสินค้าหรือตัวเลือกสินค้า จากนั้น Shoply จะคำนวณสถานะพร้อมจำหน่ายจากสต็อก (quantity > 0) และเก็บ total_inventory สำหรับรายการในแอดมิน
• source ใช้ระบุการเชื่อมต่อแค็ตตาล็อก (ไม่จำเป็นต้องเป็นแพลตฟอร์ม) ใช้ชื่อที่คงที่ เช่น woocommerce-main อักขระที่อนุญาต: ตัวอักษรพิมพ์เล็ก ตัวเลข ขีดล่าง และขีดกลาง; สูงสุด 64 อักขระ สินค้าที่สร้างจากฟอร์มในแอดมินจะมีค่า source เริ่มต้นเป็น admin
• เอกลักษณ์ของสินค้าคือการรวมกันของ store, source และ external ID การ upsert ผ่าน POST แบบเดี่ยวและแบบ batch เป็นการแทนที่ทั้งหมด ไม่ใช่ patch: ฟิลด์เสริมที่ละไว้จะถูกล้าง ใช้ PATCH สำหรับการอัปเดตบางส่วน
• แต่ละ batch มีสินค้าได้ 1–50 รายการ และมีขนาดคำขอรวมได้ไม่เกิน 2,000,000 ไบต์ JSON ที่ผ่านการตรวจสอบของสินค้าแต่ละรายการจำกัดที่ 128,000 ไบต์ และมีตัวเลือกสินค้าได้ไม่เกิน 250 รายการ
• แนะนำให้ใช้สตริงเลขฐานสิบสำหรับราคา สกุลเงินต้องเป็นรหัสตัวพิมพ์ใหญ่ 3 ตัวอักษร
• URL ของสินค้าและรูปภาพต้องเป็น HTTP(S) การนำเข้าไม่ได้ดึงข้อมูลจาก URL เหล่านั้นให้คุณ
• ใช้ metafields แบบสาธารณะสำหรับสเปกสินค้าที่ค้นหาได้ (เทียบเท่ากับ Shopify product metafields ของ SiteChat) ค่าแต่ละรายการต้องเป็นสตริงธรรมดา attributes แบบเดิมยังยอมรับในฐานะชื่อแทน ไม่รองรับ metadata แบบส่วนตัวของสินค้าอีกต่อไป
• สินค้าที่เป็น draft และ archived จะไม่ถูกรวมในดัชนีที่เผยแพร่ครั้งถัดไป สินค้าที่เผยแพร่แล้วแต่ขายหมดจะยังคงอยู่ในดัชนีพร้อมข้อมูลสถานะพร้อมจำหน่าย
• manual collections จะเก็บ title, description, status และรายการการเป็นสมาชิกของสินค้า (source + external_id) รุ่นนี้ยังไม่รองรับ smart/rule-based collections

ตัวอย่างการตอบกลับเมื่อสำเร็จ

{
  "results": [
    {
      "external_id": "123",
      "product_id": "sitechat_product::woocommerce-main::<sha256-of-external-id>",
      "status": "stored"
    }
  ],
  "index_status": "pending",
  "index_revision": 1
}

Shoply จะตรวจสอบคำขอทั้งหมดก่อนเขียนข้อมูล HTTP 200 ยังอาจแสดงผลลัพธ์บางรายการเป็น failed พร้อม error: "storage_error" ได้ ตรวจสอบผลลัพธ์ทุกตัวและลองส่งสินค้าที่ล้มเหลวใหม่อีกครั้ง หาก index_status เป็น request_failed แปลว่าการจัดเก็บสำเร็จแล้ว แต่ยังไม่ได้ตั้งเวลาสำหรับการทำดัชนี—ให้ลองส่งสินค้าที่ถูกจัดเก็บแล้วซ้ำอีกครั้งเช่นกัน

ตัวอย่าง Python

import json
import os
import requests
 
store_key = os.environ["SHOPLY_STORE_KEY"]
headers = {
    "Authorization": json.dumps({
        "store_key": store_key,
        "store_owner_api_secrete": os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
    })
}
 
response = requests.post(
    "https://api.shoplyai.ai/merchant/products/batch",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "custom",
        "products": [{
            "external_id": "123",
            "title": "Trail shoes",
            "url": "https://example.com/products/trail-shoes",
            "currency": "USD",
            "price": "49.95",
            "available": True,
        }],
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
failed = [item["external_id"] for item in result["results"] if item["status"] != "stored"]
if failed:
    raise RuntimeError(f"Products need retry: {failed}")
if result["index_status"] == "request_failed":
    raise RuntimeError("Products saved, but retry the batch to request indexing")

ฉันจะตรวจสอบสินค้าที่นำเข้าแล้วได้อย่างไร?

GET https://api.shoplyai.ai/merchant/products?store_key=YOUR_SITECHAT_STORE_KEY&source=woocommerce-main&external_id=123

ใช้เฮดเดอร์ Authorization เดิม การตอบกลับจะมี schema_version, updated_at, index_status และ product ที่ผ่านการทำให้เป็นมาตรฐานแล้ว ระเบียนที่ไม่มีอยู่จะคืนค่า HTTP 404

หลังจากตัวทำดัชนีเบื้องหลังเผยแพร่การสร้างใหม่แล้ว สถานะการอ่านกลับรายสินค้าจะเป็น indexed, excluded (สำหรับสินค้าที่เป็น draft หรือ archived) หรือ limit_exceeded ใช้ GET /merchant/products/list สำหรับการแสดงรายการในแอดมิน ทำ soft-archive ด้วย DELETE /merchant/products (หรือตั้ง status เป็น archived / draft) เพื่อไม่ให้สินค้าปรากฏในดัชนีที่เผยแพร่ครั้งถัดไป; ในรุ่นนี้ยังไม่มี hard-delete

record = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={
        "store_key": store_key,
        "source": "woocommerce-main",
        "external_id": "123",
    },
    headers=headers,
    timeout=30,
)
record.raise_for_status()
print(record.json()["index_status"], record.json()["product"]["title"])

ฉันสามารถอัปโหลดรูปภาพสินค้าได้ไหม?

ได้ หากรูปภาพมีอยู่แล้วที่ URL HTTPS สาธารณะที่ใช้งานได้ถาวร ให้นำ URL นั้นใส่ในรายการ images ของสินค้า หรือในฟิลด์ image ของตัวเลือกสินค้า URL HTTPS แบบสาธารณะของ S3 ใช้งานได้ แต่พาธ s3:// แบบดิบและ signed URL ที่มีอายุสั้นใช้ไม่ได้

หากต้องการให้ Shoply โฮสต์ไฟล์ ให้อัปโหลดไบต์รูปภาพดิบจากแบ็กเอนด์ของคุณ:

POST https://api.shoplyai.ai/merchant/products/images?store_key=YOUR_SITECHAT_STORE_KEY
Content-Type: image/png

ส่งเป็น raw file bytes ไม่ใช่ JSON, base64 หรือ multipart form data รองรับ JPEG, PNG และ WebP สูงสุด 10 MiB และ 20 million pixels ไม่รองรับภาพเคลื่อนไหว Shoply จะเปลี่ยนรูปภาพเป็น WebP และลบ metadata ที่ฝังมาออก

with open("trail-shoes.png", "rb") as image_file:
    response = requests.post(
        "https://api.shoplyai.ai/merchant/products/images",
        params={"store_key": store_key},
        headers={**headers, "Content-Type": "image/png"},
        data=image_file,
        timeout=60,
    )
response.raise_for_status()
image_url = response.json()["url"]

HTTP 201 จะคืนค่า url, content_type, size_bytes, width และ height การอัปโหลดรูปภาพเพียงอย่างเดียวจะยังไม่ผูกกับสินค้าและไม่ร้องขอการทำดัชนี ให้นำ URL ที่ได้กลับมาใส่ในสินค้าที่สมบูรณ์ แล้วส่งอีกครั้งผ่าน /merchant/products/batch

หากอัปโหลดรูปเดิมอีกครั้งสำหรับบัญชีเดียวกัน ระบบจะใช้ URL เดิมซ้ำ หากรูปภาพมีการเปลี่ยนแปลงจะได้รับ URL ใหม่ ในรุ่นนี้ยังไม่มีเอ็นด์พอยต์สำหรับลบรูปภาพ

สินค้าจะปรากฏในแชตและการค้นหาเมื่อไร?

หลังจากบันทึก batch สำเร็จ Shoply จะร้องขอการสร้างดัชนีเบื้องหลังใหม่ การตอบกลับจะรายงาน index_status: "pending" จนกว่า worker จะเผยแพร่ดัชนีใหม่ ยังไม่มีการรับประกันเวลาที่แน่นอนว่าจะเสร็จเมื่อใด

• สินค้าที่เผยแพร่แล้วจะเข้าสู่ทั้งการค้นหาสินค้าและฐานความรู้ที่ SiteChat chat ใช้
• สินค้าที่เป็น draft และ archived จะถูกตัดออกในการสร้างใหม่ครั้งถัดไป
• หากไม่ได้ตั้งเวลาการทำดัชนี (index_status: "request_failed") ให้ลองส่ง batch ใหม่สำหรับสินค้าที่จัดเก็บสำเร็จไปแล้ว

ฉันควรคาดหวังข้อผิดพลาดอะไรบ้าง?

secret จะหมดอายุหลังจาก 90 วัน สร้างตัวแทนใหม่ใน Settings → Store owner API secret ก่อนหมดอายุ และเพิกถอน secret ใด ๆ ที่คุณไม่ต้องใช้อีกต่อไป secret เดียวกันนี้ยังสามารถใช้เรียกเอ็นด์พอยต์ด้าน analytics, conversation และ knowledge ที่อธิบายไว้ใน คู่มือ Merchant API ได้ด้วย

หากต้องการความช่วยเหลือเกี่ยวกับการเชื่อมต่อ ติดต่อ Shoply AI.