Cách tải danh mục 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 đến Shoply để người mua sắm 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 danh mục thông qua Shopify; các tuyến tải lên này chỉ khả dụng cho các tài khoản SiteChat chưa đồng bộ danh mục Magento.

Trong phần quản trị SiteChat, Product Catalog mở ra một khu vực theo 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?

Khi lưu sản phẩm thành công, Shoply sẽ được yêu cầu 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 cả trong chỉ mục sản phẩm lẫn trong 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 mọi tên miền *.myshopify.com) sẽ bị từ chối.
• Xác thực phải sử dụng hoặc là 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 tuyến này.

Hãy tạo hoặc xoay vòng khóa bí mật chủ sở hữu 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 trình kết nối máy chủ

Gọi API từ một backend đáng tin cậy qua HTTPS. Đặt một chuỗi JSON trong 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ử đó. store_owner_api_secret cũng được chấp nhận. Đây không phải là token Bearer.

Từ phần quản trị SiteChat

Trang Product Catalog sẽ gửi phiên quản trị đã đăng nhập của bạn thay vào đó:

{
  "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ỉ giữ khóa bí mật chủ sở hữu trong các biến môi trường phía máy chủ — tuyệt đối không đặt trong script storefront, URL hoặc kho mã 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 sản phẩm lên?

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à một quantity không âm trên sản phẩm hoặc biến thể. Khi đó Shoply sẽ suy ra khả dụng từ tồn kho (quantity > 0) và lưu total_inventory cho các danh sách quản trị.
• source đặt tên cho kết nối danh mục (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 phần quản trị mặc định có source là admin.
• Định danh sản phẩm là tổ hợp của cửa hàng, source và external ID. Các thao tác upsert POST theo lô và đơn 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 cho các 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 đã 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ã viết hoa gồm ba chữ cái.
• URL sản phẩm và hình ảnh phải là HTTP(S). Việc nhập không tự động truy xuất các URL đó cho bạn.
• Sử dụng metafields công khai cho các thông số sản phẩm có thể tìm kiếm được (tương tự product metafields của Shopify trong SiteChat). Giá trị phải là chuỗi thuần. attributes cũ đượ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ợ.
• 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 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 theo trạng thái khả dụng.
• Các bộ sưu tập thủ công lưu tiêu đề, mô tả, trạng thái và danh sách thành viên sản phẩm (source + external_id). Các 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. Một 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 từng kết quả và thử lại các sản phẩm thất bạ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 bả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ữ một sản phẩm không xuất hiện trong chỉ mục đã xuất bản ở lần xây dựng tiếp theo; trong bản phát hành này không có 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"])

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

Có. Nếu một 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ể. Các URL HTTPS công khai của S3 hoạt động. Các đường dẫn s3:// thô và URL có chữ ký sống ngắn thì không.

Để Shoply lưu trữ tệp, hãy tải lên byte ả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 byte tệp thô, 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à loại bỏ metadata 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. Chỉ tải lên một hình ảnh sẽ 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 được 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. Nếu hình ảnh thay đổi, nó sẽ nhận một URL mới. Trong bản phát hành này không có endpoint xóa hình ảnh.

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 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 lẫn nguồn tri thức được SiteChat chat sử dụng.
• 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 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 nữa. Cùng khóa bí mật đó cũng có thể gọi các endpoint về phân tích, hội thoại và tri thức được ghi trong hướng dẫn Merchant API.

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