วิธีอัปโหลดแคตตาล็อกของคุณสำหรับ 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 จัดกลุ่มสินค้าเป็นคอลเลกชันแบบกำหนดเอง และปรับจำนวนสต็อกได้

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

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

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

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

สร้างหรือหมุนเวียน 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 ได้

พารามิเตอร์คิวรี store_key ต้องตรงกับเฮดเดอร์ เก็บ owner secrets ไว้เฉพาะในตัวแปรสภาพแวดล้อมฝั่งเซิร์ฟเวอร์เท่านั้น—ห้ามใส่ไว้ในสคริปต์หน้าร้าน, 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 ที่ไม่ติดลบบนสินค้าหรือ variant จากนั้น Shoply จะคำนวณสถานะพร้อมขายจากสต็อก (quantity > 0) และจัดเก็บ total_inventory สำหรับรายการแอดมิน
• source ใช้ระบุการเชื่อมต่อแคตตาล็อก (ไม่จำเป็นต้องเป็นแพลตฟอร์มเสมอไป) ควรใช้ชื่อที่คงที่ เช่น woocommerce-main อักขระที่อนุญาต: ตัวอักษรพิมพ์เล็ก ตัวเลข ขีดล่าง และขีดกลาง; ยาวได้สูงสุด 64 อักขระ สินค้าที่สร้างผ่านฟอร์มในแอดมินจะใช้ source เริ่มต้นเป็น admin
• ตัวตนของสินค้าคือการรวมกันของ store, source และ external ID การ upsert แบบ POST เดี่ยวและแบบแบตช์เป็นการ แทนที่ทั้งหมด ไม่ใช่การ patch: ฟิลด์ทางเลือกที่ละไว้จะถูกล้าง ใช้ PATCH สำหรับการอัปเดตบางส่วน
• แต่ละแบตช์มีสินค้าได้ 1–50 รายการ และมีขนาดคำขอได้ไม่เกิน 2,000,000 ไบต์ JSON ที่ผ่านการตรวจสอบของสินค้าแต่ละรายการจำกัดที่ 128,000 ไบต์ และมี variants ได้ไม่เกิน 250 รายการ
• ควรใช้สตริงทศนิยมสำหรับราคา Currency ต้องเป็นรหัสตัวพิมพ์ใหญ่ 3 ตัวอักษร
• URL ของสินค้าและรูปภาพต้องเป็น HTTP(S) การนำเข้าไม่ได้ดึงข้อมูลจาก URL เหล่านั้นให้คุณ
• ใช้ metafields แบบ public สำหรับสเปกสินค้าที่ค้นหาได้ (เทียบได้กับ Shopify product metafields ของ SiteChat) ค่าในนั้นต้องเป็นสตริงธรรมดา attributes แบบเดิมยังคงรองรับในฐานะชื่อแทน ไม่รองรับ metadata แบบ private ของสินค้าอีกต่อไป
• สินค้า draft และ archived จะไม่ถูกใส่ในดัชนีที่เผยแพร่ครั้งถัดไป สินค้าที่เผยแพร่แล้วแต่หมดสต็อกจะยังคงอยู่ในดัชนีพร้อมข้อมูลสถานะพร้อมขาย
• คอลเลกชันแบบกำหนดเองจะเก็บ title, description, status และรายการสมาชิกสินค้า (source + external_id) คอลเลกชันแบบอัจฉริยะ/อิงกฎยังไม่รองรับในรีลีสนี้

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

{
  "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) เพื่อกันสินค้าออกจากดัชนีที่เผยแพร่ครั้งถัดไป; ในรีลีสนี้ยังไม่มีการลบแบบถาวร

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"])

ฉันจะอัปเดต Variants หรือ Metafields อย่างปลอดภัยได้อย่างไร?

สำหรับ PATCH ที่มี variants, metafields หรือฟิลด์ attributes แบบเดิม ให้เริ่มจากอ่านสินค้าด้วย GET ก่อน สร้างการแก้ไขจากข้อมูลตอบกลับนั้น แล้วใส่ค่า updated_at ระดับบนสุดของข้อมูลนั้นเป็น expected_updated_at ในเนื้อหา PATCH ข้อนี้ใช้กับการล้าง variants หรือ metafields ด้วยเช่นกัน

current_response = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key, "source": "woocommerce-main", "external_id": "123"},
    headers=headers,
    timeout=30,
)
current_response.raise_for_status()
current = current_response.json()
updated_metafields = {**current["product"].get("metafields", {}), "material": "Leather"}
response = requests.patch(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "woocommerce-main",
        "external_id": "123",
        "expected_updated_at": current["updated_at"],
        "metafields": updated_metafields,
    },
    timeout=30,
)
response.raise_for_status()

HTTP 409 หมายความว่าไม่มีเวอร์ชัน หรือมีการอัปเดตอื่นเปลี่ยนสินค้านั้นไปแล้ว ให้อ่านสินค้าล่าสุด และรวมการเปลี่ยนแปลงที่คุณต้องการอีกครั้งก่อนลองใหม่ อย่าแนบเวอร์ชันใหม่เข้ากับรายการ variants เก่า เพราะอาจเขียนทับค่าสต็อกที่ใหม่กว่าได้

การเชื่อมต่อเดิมที่ PATCH ฟิลด์เหล่านี้โดยไม่มีเวอร์ชันจำเป็นต้องอัปเดต คำขอ PATCH ที่มีเฉพาะ scalar, การปรับสต็อกโดยเฉพาะ และการแทนที่ทั้งหมดผ่าน POST หรือการนำเข้าแบบแบตช์ ไม่จำเป็นต้องใช้ฟิลด์นี้ อย่างไรก็ตาม การแทนที่ทั้งหมดก็ยังคงแทนที่สินค้าทั้งรายการอยู่ดี

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

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

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

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

ส่งเป็น ไบต์ไฟล์ดิบ ไม่ใช่ JSON, base64 หรือ multipart form data รองรับ JPEG, PNG และ WebP ขนาดไม่เกิน 10 MiB และ 20 ล้านพิกเซล ไม่รองรับภาพเคลื่อนไหว 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 ใหม่ ในรีลีสนี้ยังไม่มีเอ็นด์พอยต์สำหรับลบรูป

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

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

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

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

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

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