Cách tải catalog của bạn lên cho SiteChat

Nếu bạn sử dụng SiteChat trên website riêng của mình (không phải cửa hàng Shopify), bạn có thể gửi các bản ghi sản phẩm có cấu trúc tới Shoply để người mua có thể tìm thấy chúng trong phần chat SiteChat và tìm kiếm sản phẩm.

Các endpoint này sử dụng cùng Settings → Store owner API secret như phần còn lại của Shoply Merchant API, và trang Product Catalog trong quản trị SiteChat có thể gọi chúng bằng access token quản trị khi bạn đã đăng nhập. Các cửa hàng Shopify tiếp tục đồng bộ dữ liệu catalog thông qua Shopify; các route tải lên này chỉ khả dụng cho các tài khoản SiteChat chưa đồng bộ catalog Magento.

Trong phần quản trị SiteChat, Product Catalog mở ra một khu vực kiểu Shopify với Products, Collections và Inventory. Bạn có thể thêm hoặc chỉnh sửa sản phẩm, nhập CSV/Excel, nhóm sản phẩm vào các bộ sưu tập thủ công và điều chỉnh số lượng tồn kho.

Có những API nào khả dụng?

Các lần lưu sản phẩm thành công sẽ yêu cầu Shoply xây dựng lại chỉ mục cửa hàng. Cho đến khi quá trình xây dựng lại hoàn tất, phản hồi sẽ báo index_status: "pending". Sau đó, các sản phẩm đã xuất bản sẽ xuất hiện trong cả chỉ mục sản phẩm và nguồn tri thức được SiteChat chat sử dụng.

Ai có thể sử dụng các API này?

• Cửa hàng của bạn phải là tài khoản SiteChat (app_platform là SiteChat).
• Khóa cửa hàng Shopify (bao gồm bất kỳ miền *.myshopify.com nào) sẽ bị từ chối.
• Xác thực phải sử dụng hoặc khóa bí mật API chủ cửa hàng hợp lệ hoặc access token quản trị SiteChat cho đúng store_key trong yêu cầu.
• Token Shopify Admin API không thể gọi các route này.

Hãy tạo hoặc xoay vòng khóa bí mật của chủ cửa hàng giống như với các tích hợp Merchant API khác: Cách sử dụng Shoply Merchant API. Trong bảng điều khiển quản trị SiteChat, mở Product Catalog để quản lý sản phẩm, bộ sưu tập và tồn kho—hoặc nhập tệp CSV hay Excel—mà không cần tự quản lý khóa bí mật.

Xác thực hoạt động như thế nào?

Từ một server connector

Gọi API từ backend đáng tin cậy qua HTTPS. Đặt một chuỗi JSON vào header Authorization:

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

store_owner_api_secrete là tên trường công khai, bao gồm cả cách viết lịch sử này. store_owner_api_secret cũng được chấp nhận. Đây không phải token Bearer.

Từ phần quản trị SiteChat

Trang Product Catalog sẽ gửi phiên quản trị mà bạn đã đăng nhập thay thế:

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

access_token được chấp nhận như một bí danh của admin_auth_token.

Tham số truy vấn store_key phải khớp với header. Chỉ lưu khóa bí mật của chủ cửa hàng trong biến môi trường phía máy chủ—không bao giờ đặt trong script storefront, URL hoặc kho lưu trữ công khai.

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

Làm cách nào để tải lên sản phẩm?

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

Các trường bắt buộc và quy tắc

• Các trường sản phẩm bắt buộc: external_id, title, url, currency, price và available. status mặc định là published.
• Tồn kho tùy chọn: đặt tracks_inventory thành true và quantity không âm trên sản phẩm hoặc biến thể. Khi đó Shoply sẽ suy ra tình trạng còn hàng từ tồn kho (quantity > 0) và lưu total_inventory cho danh sách quản trị.
• source đặt tên cho kết nối catalog (không nhất thiết là một nền tảng). Hãy dùng một tên ổn định như woocommerce-main. Ký tự được phép: chữ thường, số, dấu gạch dưới và dấu gạch nối; tối đa 64 ký tự. Các sản phẩm được tạo bằng biểu mẫu trong trang quản trị mặc định có source là admin.
• Danh tính sản phẩm là tổ hợp của store, source và external ID. Các thao tác upsert bằng POST đơn lẻ và theo lô là thay thế hoàn toàn, không phải patch: các trường tùy chọn bị bỏ qua sẽ bị xóa. Hãy dùng PATCH để cập nhật một phần.
• Mỗi lô chứa từ 1–50 sản phẩm và tối đa 2.000.000 byte yêu cầu. JSON đã được xác thực của mỗi sản phẩm bị giới hạn ở 128.000 byte, với tối đa 250 biến thể.
• Nên dùng chuỗi thập phân cho giá. Tiền tệ là mã chữ in hoa gồm ba ký tự.
• URL sản phẩm và hình ảnh phải là HTTP(S). Quá trình nhập sẽ không tự tải các URL đó cho bạn.
• Dùng metafields công khai cho các thông số sản phẩm có thể tìm kiếm (tương đương metafields sản phẩm Shopify trong SiteChat). Giá trị phải là chuỗi thuần. attributes cũ vẫn được chấp nhận như một bí danh. metadata riêng tư của sản phẩm không còn được hỗ trợ.
• Các sản phẩm draft và archived sẽ bị loại khỏi chỉ mục đã xuất bản ở lần xây dựng lại tiếp theo. Các sản phẩm đã xuất bản nhưng hết hàng vẫn được lập chỉ mục kèm trạng thái còn hàng.
• Bộ sưu tập thủ công lưu tiêu đề, mô tả, trạng thái và danh sách sản phẩm thành viên (source + external_id). Bộ sưu tập thông minh/dựa trên quy tắc chưa được hỗ trợ trong bản phát hành này.

Ví dụ phản hồi thành công

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

Shoply xác thực toàn bộ yêu cầu trước khi ghi dữ liệu. HTTP 200 vẫn có thể liệt kê một số kết quả failed với error: "storage_error". Hãy kiểm tra mọi kết quả và thử lại các sản phẩm bị lỗi. Nếu index_status là request_failed, việc lưu trữ đã thành công nhưng việc lập chỉ mục chưa được lên lịch—hãy thử lại cả các sản phẩm đã được lưu đó.

Ví dụ 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")

Làm cách nào để xác minh một sản phẩm đã nhập?

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

Sử dụng cùng header Authorization. Phản hồi bao gồm schema_version, updated_at, index_status và product đã được chuẩn hóa. Các bản ghi không tồn tại sẽ trả về HTTP 404.

Sau khi trình lập chỉ mục nền xuất bản một lần xây dựng lại, trạng thái đọc lại theo từng sản phẩm sẽ trở thành indexed, excluded (đối với sản phẩm draft hoặc archived) hoặc limit_exceeded. Hãy dùng GET /merchant/products/list để liệt kê trong quản trị. Lưu trữ mềm bằng DELETE /merchant/products (hoặc đặt status thành archived / draft) để giữ sản phẩm không xuất hiện trong chỉ mục đã xuất bản tiếp theo; không có hard-delete trong bản phát hành này.

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

Làm cách nào để cập nhật variants hoặc metafields một cách an toàn?

Đối với PATCH có chứa variants, metafields hoặc trường cũ attributes, trước tiên hãy đọc sản phẩm bằng GET. Tạo phần chỉnh sửa từ phản hồi đó và đưa giá trị updated_at cấp cao nhất của phản hồi vào expected_updated_at trong body PATCH. Điều này cũng áp dụng khi xóa variants hoặc 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 nghĩa là thiếu phiên bản hoặc một cập nhật khác đã thay đổi sản phẩm. Hãy đọc sản phẩm mới nhất và hợp nhất lại các thay đổi bạn muốn thực hiện trước khi thử lại. Không gắn một phiên bản mới vào danh sách variants cũ: điều đó có thể ghi đè các giá trị tồn kho mới hơn.

Các tích hợp hiện có đang PATCH các trường này mà không có phiên bản cần được cập nhật. Các yêu cầu PATCH chỉ với scalar, các điều chỉnh tồn kho chuyên biệt và các thay thế hoàn toàn thông qua POST hoặc nhập theo lô không yêu cầu trường này. Các thay thế hoàn toàn vẫn sẽ thay thế toàn bộ sản phẩm.

Tôi có thể tải lên hình ảnh sản phẩm không?

Có. Nếu hình ảnh đã có sẵn tại một URL HTTPS công khai ổn định, hãy đặt URL đó vào danh sách images của sản phẩm hoặc trường image của biến thể. URL HTTPS công khai của S3 hoạt động được. Đường dẫn s3:// thô và URL đã ký có thời hạn ngắn thì không.

Để Shoply lưu trữ tệp, hãy tải lên byte hình ảnh thô từ backend của bạn:

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

Hãy gửi raw file bytes, không phải JSON, base64 hoặc dữ liệu biểu mẫu multipart. JPEG, PNG và WebP được chấp nhận, tối đa 10 MiB và 20 triệu pixel. Hình ảnh động không được hỗ trợ. Shoply sẽ chuyển đổi hình ảnh sang WebP và xóa metadata được nhúng.

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 trả về url, content_type, size_bytes, width và height. Việc chỉ tải lên một hình ảnh không tự gắn nó vào sản phẩm hoặc yêu cầu lập chỉ mục. Hãy đưa URL đã trả về vào một sản phẩm hoàn chỉnh và gửi lại qua /merchant/products/batch.

Nếu cùng một hình ảnh được tải lên lại cho cùng một tài khoản, URL của nó sẽ được tái sử dụng. Hình ảnh đã thay đổi sẽ nhận URL mới. Không có endpoint xóa hình ảnh trong bản phát hành này.

Khi nào sản phẩm xuất hiện trong chat và tìm kiếm?

Sau khi lưu lô thành công, Shoply sẽ yêu cầu xây dựng lại chỉ mục nền. Phản hồi sẽ báo index_status: "pending" cho đến khi worker xuất bản chỉ mục mới. Không có cam kết cố định về thời gian hoàn tất.

• Các sản phẩm đã xuất bản sẽ đi vào cả tìm kiếm sản phẩm và nguồn tri thức được SiteChat chat sử dụng.
• Các sản phẩm draft và archived sẽ bị loại ở lần xây dựng lại tiếp theo.
• Nếu việc lập chỉ mục chưa được lên lịch (index_status: "request_failed"), hãy thử lại lô cho các sản phẩm đã được lưu thành công.

Tôi nên mong đợi những lỗi nào?

Khóa bí mật sẽ hết hạn sau 90 ngày. Hãy tạo khóa thay thế trong Settings → Store owner API secret trước khi hết hạn, và thu hồi mọi khóa bí mật bạn không còn cần. Cùng khóa bí mật đó cũng có thể gọi các endpoint analytics, conversation và knowledge được ghi lại trong hướng dẫn Merchant API.

Để được hỗ trợ về tích hợp, liên hệ Shoply AI.