Cách sử dụng API Tìm kiếm Shoply AI

Có. Bạn có thể truy vấn Shoply AI Search theo cách lập trình từ backend của riêng mình mà không cần tải tiện ích tại chỗ hoặc gửi yêu cầu thông qua storefront Shopify của bạn.

API tìm kiếm tiêu chuẩn khả dụng trên mọi gói Shopify có bao gồm AI Search, kể cả Forever Free. Các yêu cầu API sử dụng cùng hạn mức tìm kiếm hằng tháng như các lượt tìm kiếm được thực hiện thông qua tiện ích storefront. Xem các giới hạn hiện tại trên trang giá của chúng tôi.

Nếu bạn cần giới hạn cao hơn, thỏa thuận mức dịch vụ, nguồn dữ liệu tùy chỉnh hoặc một tích hợp không sử dụng danh mục Shopify được Shoply lập chỉ mục, hãy liên hệ với chúng tôi về gói Enterprise.

Trước khi bắt đầu

Hãy cài đặt Shoply AI trên cửa hàng Shopify có danh mục mà bạn muốn tìm kiếm và chờ quá trình lập chỉ mục sản phẩm ban đầu hoàn tất. Bạn sẽ cần tên miền myshopify.com cố định của cửa hàng, ví dụ như:

your-store.myshopify.com

API có thể được gọi từ bất kỳ môi trường backend nào. Không cần một API key riêng cho endpoint tìm kiếm sản phẩm tiêu chuẩn vì endpoint này trả về cùng thông tin danh mục công khai mà Shoply có thể hiển thị trong trải nghiệm tìm kiếm trên storefront.

Endpoint

POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

Nội dung yêu cầu

query là một chuỗi JSON nằm trong nội dung yêu cầu, không phải một đối tượng JSON lồng nhau. Ví dụ, cụm từ tìm kiếm waterproof hiking boots được gửi như sau:

"{\"keywords\":\"waterproof hiking boots\"}"

Ví dụ cURL

Thay your-store.myshopify.com bằng tên miền Shopify cố định của cửa hàng bạn:

curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

Ví dụ JavaScript

// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Ví dụ Python

import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

Phản hồi

Một yêu cầu thành công sẽ trả về:

{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

• num_results là tổng số sản phẩm khớp.
• docs chứa các sản phẩm được xếp hạng cho trang được yêu cầu.
• display_filters chứa các bộ lọc khả dụng như giá, thương hiệu, màu sắc hoặc các thuộc tính khác tùy theo danh mục.

Các đối tượng sản phẩm có thể chứa thêm các trường khác tùy thuộc vào danh mục của cửa hàng, biến thể, giá và cấu hình Shoply. Ứng dụng khách nên sử dụng các trường mình cần và có thể bỏ qua an toàn những trường không quen thuộc.

Phân trang

Sử dụng start và limit để yêu cầu thêm kết quả. Ví dụ: sau khi yêu cầu tám sản phẩm với start: 0 và limit: 8, hãy yêu cầu trang tiếp theo với:

{
  "start": 8,
  "limit": 8
}

Dừng lại khi start + docs.length lớn hơn hoặc bằng num_results, hoặc khi docs trống.

Ghi chú về gói và tích hợp

Nếu storefront tùy chỉnh của bạn cũng cần tính năng hội thoại, hãy thêm chat vào storefront Shopify headless.

• Tìm kiếm API tiêu chuẩn là tự phục vụ và không yêu cầu tiện ích tại chỗ.
• Cửa hàng Shopify của bạn phải tiếp tục được kết nối với Shoply AI để chỉ mục sản phẩm luôn được cập nhật.
• Lượt tìm kiếm qua API và lượt tìm kiếm trên storefront dùng chung hạn mức tìm kiếm hằng tháng của gói Shopify của bạn.
• Hãy giữ lệnh gọi ở backend nếu bạn muốn tập trung hóa việc lưu đệm, ghi log, thử lại hoặc kiểm soát truy cập.
• Hãy liên hệ với chúng tôi để được hỗ trợ Enterprise nếu bạn cần xác thực tùy chỉnh, thông lượng được đảm bảo, SLA, danh mục không phải Shopify hoặc giới hạn vượt ngoài các gói đã công bố.

Để được hỗ trợ xác nhận store key của bạn hoặc lên kế hoạch cho tích hợp production, hãy liên hệ với Shoply AI.