如何使用 Shoply AI Search API

Shoply AI Search API connecting backend code to storefront product search results

可以。你可以直接從自己的後端以程式方式查詢 Shoply AI Search，而無需載入網站上的小工具，也無需透過你的 Shopify 店面發送請求。

標準搜尋 API 適用於所有包含 AI Search 的 Shopify 方案，包括 Forever Free。API 請求與透過店面小工具進行的搜尋，共用相同的每月搜尋額度。請在我們的定價頁面查看目前限制。

如果你需要更高的限制、服務級別協議、自訂資料來源，或是不使用 Shoply 已建立索引的 Shopify 商品目錄之整合方案，歡迎聯絡我們了解 Enterprise 方案。

開始之前

請先在你要搜尋其商品目錄的 Shopify 商店安裝 Shoply AI，並等待首次商品索引完成。你需要該商店的永久 myshopify.com 網域，例如：

text


your-store.myshopify.com

API 可從任何後端環境呼叫。標準商品搜尋端點不需要另外的 API 金鑰，因為它回傳的是與 Shoply 可在店面搜尋體驗中顯示的相同公開商品目錄資訊。

端點

text


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

請求主體

欄位	必填	說明
`store_key`	是	你的商店永久 `myshopify.com` 網域
`query`	是	一個 JSON 編碼字串，當中至少包含 `keywords` 欄位
`start`	否	用於分頁的從零開始結果偏移量；預設為 `0`
`limit`	否	要回傳的商品數量上限；預設為 `4`

query 是請求主體中的 JSON 字串，而不是巢狀 JSON 物件。例如，搜尋詞組 waterproof hiking boots 會以以下方式傳送：

json


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

cURL 範例

請將 your-store.myshopify.com 替換為你的商店永久 Shopify 網域：

bash


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
  }'

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);

Python 範例

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

回應

成功的請求會回傳：

json


{
  "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 是符合條件商品的總數。
docs 包含所請求頁面的排序後商品。
display_filters 包含可用篩選條件，例如價格、品牌、顏色或其他商品目錄特定屬性。

商品物件可能會因商店的商品目錄、變體、定價及 Shoply 設定而包含其他欄位。用戶端應使用所需欄位，並安全地忽略不熟悉的欄位。

分頁

使用 start 和 limit 來請求更多結果。例如，在以 start: 0 和 limit: 8 請求八件商品後，可使用以下方式請求下一頁：

json


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

當 start + docs.length 大於或等於 num_results，或 docs 為空時，即可停止。

方案與整合注意事項

如果你的自訂店面同時也需要對話功能，可為 headless Shopify 店面加入聊天功能。

標準 API 搜尋可自行設定，且不需要網站上的小工具。
你的 Shopify 商店必須保持連接至 Shoply AI，讓其商品索引可維持最新狀態。
API 搜尋與店面搜尋共用你 Shopify 方案的每月搜尋額度。
如果你希望集中管理快取、記錄、重試或存取控制，請將呼叫保留在你的後端。
如果你需要自訂驗證、保證吞吐量、SLA、非 Shopify 商品目錄，或超出已公布方案的限制，請聯絡我們以取得 Enterprise 支援。

如需協助確認你的 store key 或規劃正式上線的整合方案，請聯絡 Shoply AI。