如何使用 Shoply AI Search API
你可以從自己的後端查詢 Shoply AI Search,而無需載入 Shoply 的店面小工具,也不用透過你的店面轉送請求。此 API 適用於 Shopify 商店,以及使用 SiteChat(Shoply 為任何網站提供的 AI 助手)的其他平台網站。
標準 Search API 在所有 Shoply 方案中均可使用,包括 Forever Free,適用於 Shopify 商店及 SiteChat 網站。每個方案可索引的產品數量不同;請參閱我們的定價頁面。透過 API 進行的搜尋不會顯示在你的 Shoply 分析資料中。
如果你預期會有高流量或穩定的 API 流量,或你需要服務等級協議、自訂驗證、保證吞吐量,或自訂資料來源,請聯絡我們了解 Enterprise 方案。
開始之前
每個請求都會以 store_key 指定要搜尋的目錄。你應使用的值取決於你的平台。
Shopify 商店
在你想搜尋其目錄的 Shopify 商店上安裝 Shoply AI,並等待初次產品索引完成。你的 store_key 是該商店永久的 myshopify.com 網域,即使顧客實際瀏覽的是自訂網域亦然:
your-store.myshopify.com其他平台上的網站
註冊 SiteChat ,並將你的產品目錄提供給 Shoply。Search API 只會搜尋該目錄;SiteChat 爬取的一般網頁會成為聊天知識,而不是可搜尋的產品。Shoply 可透過以下任一方式取得目錄:
- 在 SiteChat 管理後台的 Product Catalog 頁面中,逐一加入產品,或匯入 CSV 或 Excel 檔案。
- 使用 SiteChat product upload API 從你自己的系統上傳產品。
- 如果你的網站是 Magento 商店,Shoply 在爬取網站時會讀取其公開產品目錄;請參閱如何允許 Shoply crawler。
新增或修改產品後,Shoply 會先重新建立該商店的產品索引,之後這些產品才可被搜尋到。你的 store_key 是你的 SiteChat store key,也就是安裝在你網站上的 SiteChat 程式碼中的 store_key 值。
兩種平台皆適用
此 API 可從任何後端環境呼叫。標準產品搜尋端點不需要另外的 API 金鑰,因為它回傳的是與 Shoply 在店面搜尋體驗中可顯示的相同公開目錄資訊。
端點
Search API 有兩個端點。大多數整合只需要第一個。
| 端點 | 功能 |
|---|---|
POST https://api.shoplyai.ai/product_query_v2 | 回傳排序後的產品、結果數量、排序選項,以及篩選條件(在搜尋頁模式下,篩選條件有時會另外傳送) |
POST https://api.shoplyai.ai/search_display_filters | 回傳某個搜尋頁結果中未一併回傳的篩選條件;請參閱分開載入篩選條件 |
兩個端點都接受 Content-Type: application/json 的 JSON request body。
在每個請求的 URL 加上 store_key,並在 body 中送出相同的值:
https://api.shoplyai.ai/product_query_v2?store_key=your-store.myshopify.comShoply 可能會根據此 URL 值路由請求,因此即使 body 也包含該值,仍請務必加入。
請求內容
| 欄位 | 必填 | 說明 |
|---|---|---|
store_key | 是 | 你的 store key:Shopify 商店永久的 myshopify.com 網域,或你的 SiteChat store key |
query | 是 | 一個 JSON 編碼字串,當中至少包含 keywords 欄位 |
start | 否 | 用於分頁的從零開始結果位移;預設為 0 |
limit | 否 | 最多回傳的產品數量,範圍為 1 到 200;預設為 4 |
question_context | 否 | 用來選擇搜尋頁模式、套用篩選條件、排序結果,或設定語言的 JSON 物件;請參閱搜尋頁模式、篩選與排序 |
query 是請求 body 內的 JSON 字串,不是巢狀 JSON 物件。例如,搜尋詞 waterproof hiking boots 會這樣送出:
"{\"keywords\":\"waterproof hiking boots\"}"query 也可包含 description,即顧客以自己語言輸入的較長要求,例如 {"keywords":"boots","description":"waterproof, for wide feet"}。
請將 question_context 作為一般 JSON 物件送出,而不是字串。
cURL 範例
請將兩個位置中的 your-store.myshopify.com 都替換成你的 store key。以下範例使用 Shopify store key;SiteChat store key 的使用方式相同。
curl --request POST "https://api.shoplyai.ai/product_query_v2?store_key=your-store.myshopify.com" \
--header "Content-Type: application/json" \
--data '{
"store_key": "your-store.myshopify.com",
"query": "{\"keywords\":\"waterproof hiking boots\"}",
"start": 0,
"limit": 8
}'JavaScript 範例
此範例可在 Node.js 18 或以上版本中,以 ES module 執行(例如 .mjs 檔案)。在其他環境中,請將其包裝在 async 函式內。
const storeKey = "your-store.myshopify.com";
// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
keywords: "waterproof hiking boots"
});
const url = `https://api.shoplyai.ai/product_query_v2?store_key=${encodeURIComponent(storeKey)}`;
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
store_key: storeKey,
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 範例
import json
import requests
store_key = "your-store.myshopify.com"
# The query value is a JSON-encoded string, not a nested object.
payload = {
"store_key": store_key,
"query": json.dumps({"keywords": "waterproof hiking boots"}),
"start": 0,
"limit": 8,
}
response = requests.post(
"https://api.shoplyai.ai/product_query_v2",
params={"store_key": store_key},
json=payload,
timeout=30,
)
response.raise_for_status()
results = response.json()
print(results["docs"])回應
成功的請求會回傳如下回應,以下內容已縮短為只顯示單一產品:
{
"num_results": 34,
"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": [
{
"key": "current_price",
"name": "Price",
"selections": [
{ "value": "range_0_100", "name": "$0.00 - $99.99", "count": 12 },
{ "value": "range_100_200", "name": "$100.00 - $199.99", "count": 15 }
]
}
],
"display_filters_pending": false,
"num_results_final": true,
"sort_by": "relevance",
"sort_options": { "price": true, "rating": false }
}num_results是 Shoply 已排序的相符產品數量,上限為 200。當套用了篩選條件時,它只計算符合條件的產品。docs包含所請求頁面的排序後產品。價格、貨幣及產品連結皆以商店的預設市場為準。display_filters包含可用的篩選條件,例如價格、品牌、顏色或其他目錄特定屬性。每個篩選條件都有key、顯示用的name,以及selections清單。每個選項都有在套用篩選時要回傳的value、顯示用的name,通常也會有產品count。當商家已隱藏篩選條件,或搜尋只找到一個或沒有產品時,該清單會是空的。num_results_final在 AI 仍在檢查較低排名產品的相關性時會是false,這種情況主要出現在搜尋頁模式。在它變成true之前,num_results都只是暫定值:當檢查完成後,它可能上升或下降。Shoply 自家的搜尋頁會以加號顯示這類數字,例如「34+」。display_filters_pending只會在搜尋頁模式下為true,表示產品已先送出,但篩選條件尚未準備好。在這種情況下,display_filters會是空的;請參閱分開載入篩選條件。sort_by及sort_options用於描述排序;請參閱排序。
若要取得暫定結果的最終數量,請在約兩秒後重送相同請求。你可在重送時將 limit 設為 1。
產品 ID 取決於平台。Shopify 產品使用 Shopify ID,例如 gid://shopify/Product/1234567890。SiteChat 產品使用 Shoply 指派的 ID,因此請將 product_id 視為不透明字串。
產品物件可能會依據商店目錄、變體、定價及 Shoply 設定而包含其他欄位。篩選條件也可能包含額外欄位,例如價格範圍的 min 與 max。客戶端應使用所需欄位,並安全地忽略不認識的欄位。
分頁
使用 start 與 limit 來請求更多結果。例如,在以 start: 0 和 limit: 8 請求八個產品後,可用以下方式請求下一頁:
{
"start": 8,
"limit": 8
}當 docs 為空時即可停止。你也可以在 num_results_final 為 true,且 start + docs.length 已達到 num_results 時停止。超過第 200 個產品之後的頁面一定會是空的。
當 num_results_final 為 false 時,不要僅根據數量停止,因為它仍可能變更。後續頁面也可能重複出現先前頁面的產品,或略過某個產品,因此應去除那些 product_id 你已經顯示過的產品。
搜尋頁模式、篩選與排序
如果沒有 question_context,product_query_v2 會像 Shoply 聊天功能一樣,回傳一小段最佳相符清單。若要取得與 Shoply AI Search 頁面相同的結果,請加入 question_context,並將 ui_type 設為 search_app:
{
"store_key": "your-store.myshopify.com",
"query": "{\"keywords\":\"snowboard\"}",
"start": 0,
"limit": 24,
"question_context": {
"ui_type": "search_app"
}
}搜尋頁模式會回傳 Shoply AI Search 頁面所顯示的較長結果清單。它也會套用商家的搜尋頁設定,例如隱藏已售罄產品。若你要建立自訂搜尋結果頁面,請使用此模式。
question_context 接受以下欄位:
| 欄位 | 說明 |
|---|---|
ui_type | 設為 search_app 以取得搜尋頁結果;若要短版預設清單則省略 |
selected_filters | 要套用的篩選條件,格式為將篩選條件 key 對應至選項 value 清單的物件 |
sort_by | price_asc、price_desc 或 rating;若省略則按相關性排序 |
language_code | 顧客的語言,例如 fr。Shoply 會用它來比對關鍵字及翻譯篩選條件名稱。若省略則使用商店預設語言。 |
篩選條件
若要套用篩選條件,請從 display_filters 複製篩選條件的 key 與選項的 value。例如,以下請求只保留價格低於 $100 的產品:
{
"store_key": "your-store.myshopify.com",
"query": "{\"keywords\":\"snowboard\"}",
"start": 0,
"limit": 24,
"question_context": {
"ui_type": "search_app",
"selected_filters": {
"current_price": ["range_0_100"]
}
}
}排序
回應中的 sort_options 欄位會告訴你該商店可為該次搜尋提供哪些排序方式,例如 {"price": true, "rating": false}。若商店無法提供某種排序,或 sort_by 值無法識別,則會回退為依相關性排序。回應中的 sort_by 欄位會指出實際套用的排序方式。
分開載入篩選條件
由於建立篩選條件需要額外的 AI 步驟,因此所需時間比產品清單更長。對於搜尋頁模式中的某些短搜尋,Shoply 會先回傳產品,並在背景建立篩選條件。
Shoply 會針對每次搜尋自行決定是否如此處理,因此請務必檢查 display_filters_pending,而不要自行預測。這只會在以下條件全部成立時發生:
question_context.ui_type為search_app。- 搜尋詞只有一至兩個字詞、沒有 description,且不是產品或型號代碼。
- 前 18 個結果中,至少有 12 個已包含被搜尋的字詞。
當這種情況發生時,product_query_v2 回應會包含 display_filters_pending: true,而 display_filters 清單為空。請先立即顯示產品,然後將以下欄位 POST 到 search_display_filters:
| 欄位 | 必填 | 說明 |
|---|---|---|
store_key | 是 | 你傳送到 product_query_v2 的相同 store_key |
query | 是 | 你傳送到 product_query_v2 的相同 query 字串 |
question_context | 是 | 你傳送到 product_query_v2 的相同 question_context 物件 |
Shoply 會將每次搜尋的完整結果儲存最多一天。此端點會從該已儲存搜尋中讀取篩選條件,並透過這些欄位找到對應記錄,因此請送出與 product_query_v2 相同的值。由於篩選條件涵蓋的是整份結果清單而非單一頁面,所以不需要 start 和 limit。
回應如下:
{
"found": true,
"display_filters": [
{
"key": "current_price",
"name": "Price",
"selections": [
{ "value": "range_0_100", "name": "$0.00 - $99.99", "count": 12 }
]
}
]
}- 如果篩選條件仍在建立中,該端點在回應前最多會等待 5 秒。
- 若等待後
display_filters仍然為空,請在沒有篩選條件的情況下顯示產品。空清單也可能表示商家隱藏了篩選條件,或搜尋結果產品太少。不要只為了取得篩選條件而重新執行搜尋。 - 當 Shoply 找不到對應
store_key、query及question_context的已儲存搜尋時,found會是false。此端點本身不會執行搜尋,因此請先呼叫product_query_v2。
你不需要等篩選條件回來才套用某一個篩選。如果顧客選擇了篩選條件,照常將它放在 selected_filters 中送到 product_query_v2 即可。Shoply 會在套用該選項前,先等待自己的篩選資料準備完成。
const API_BASE = "https://api.shoplyai.ai";
// Both endpoints take store_key in the URL as well as in the body.
async function postToShoply(endpoint, body) {
const url = `${API_BASE}/${endpoint}?store_key=${encodeURIComponent(body.store_key)}`;
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
});
if (!response.ok) {
throw new Error(`Shoply ${endpoint} failed with status ${response.status}`);
}
return response.json();
}
// Returns the products at once, plus a promise for the filters, so the page can show
// products before the filters arrive.
async function searchWithFilters(storeKey, keywords) {
const searchRequest = {
store_key: storeKey,
query: JSON.stringify({ keywords }),
question_context: { ui_type: "search_app" }
};
const results = await postToShoply("product_query_v2", { ...searchRequest, start: 0, limit: 24 });
const filters = results.display_filters_pending
// Same store_key, query, and question_context, so Shoply can find the saved search.
? postToShoply("search_display_filters", searchRequest)
.then(answer => (answer.found ? answer.display_filters : []))
: Promise.resolve(results.display_filters);
return { results, filters };
}沒有 question_context 的請求,或 ui_type 並非 search_app 的請求,都會在 product_query_v2 回應中直接回傳其篩選條件。它們永遠不會設定 display_filters_pending。
錯誤
| 狀態 | 何時發生 | 處理方式 |
|---|---|---|
400 | body 不是有效 JSON、store_key 缺漏或空白、某欄位型別錯誤、query 不是 JSON 編碼物件、question_context 不是物件、start 為負數,或 limit 不在 1 到 200 範圍內 | 修正請求。回應中的 detail 欄位會指出問題。 |
409 | Shoply 找不到此 store_key 的搜尋索引:可能是 key 拼錯、傳送了 Shopify 商店的自訂網域而非其 myshopify.com 網域、該商店尚未設定 Shoply AI 或 SiteChat,或首次索引仍在建立中 | 先檢查 store_key。如果它正確且商店是最近才完成設定,請在幾分鐘後重試。 |
整合注意事項
- 若你想集中管理快取、記錄、重試或存取控制,請將呼叫保留在你的後端。
- Shopify 商店必須持續連接 Shoply AI,才能讓產品索引保持最新。SiteChat 網站的結果來自其目錄中的產品,因此請保持該目錄為最新狀態。
- 在搜尋頁模式下,請處理
display_filters_pending,讓短搜尋仍可顯示篩選條件。 - 在所有模式下,請將
num_results_final: false視為暫定數量。 - 如果你的自訂店面也需要對話功能,請參閱如何將聊天功能加入 headless Shopify storefront。
如果你需要協助確認 store key,或規劃正式環境整合,請聯絡 Shoply AI。
