A Shoply AI Search API használata

Igen. Programozottan is lekérdezheti a Shoply AI Search szolgáltatást a saját backendjéből anélkül, hogy betöltené a helyszíni widgetet, vagy a kérést a Shopify storefronton keresztül küldené.

A standard keresési API minden AI Search-t tartalmazó Shopify csomaggal elérhető, beleértve a Forever Free csomagot is. Az API-kérések ugyanazt a havi keresési keretet használják, mint a storefront widgeten keresztül végzett keresések. Az aktuális korlátokat az árképzési oldalunkon találja.

Ha magasabb limitekre, szolgáltatási szintű megállapodásra, egyedi adatforrásra vagy olyan integrációra van szüksége, amely nem Shoply által indexelt Shopify katalógust használ, lépjen kapcsolatba velünk egy Enterprise csomaggal kapcsolatban.

Mielőtt elkezdi

Telepítse a Shoply AI-t arra a Shopify áruházra, amelynek a katalógusában keresni szeretne, és várja meg, amíg az elsődleges termékindexelés befejeződik. Szüksége lesz az áruház állandó myshopify.com domainjére, például:

your-store.myshopify.com

Az API bármilyen backend környezetből meghívható. A standard termékkeresési végponthoz nincs szükség külön API-kulcsra, mert ugyanazokat a nyilvános katalógusadatokat adja vissza, amelyeket a Shoply meg tud jeleníteni a storefront keresési élményben.

Végpont

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

Kérés törzse

A query egy JSON-karakterlánc a kérés törzsén belül, nem pedig egy beágyazott JSON-objektum. Például a waterproof hiking boots keresőkifejezés így kerül elküldésre:

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

cURL példa

Cserélje le a your-store.myshopify.com értéket az áruház állandó Shopify domainjére:

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 példa

// 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 példa

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

Válasz

A sikeres kérés a következőt adja vissza:

{
  "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": []
}

• A num_results az egyező termékek teljes száma.
• A docs a kért oldalhoz tartozó, rangsorolt termékeket tartalmazza.
• A display_filters az elérhető szűrőket tartalmazza, például ár, márka, szín vagy egyéb katalógusspecifikus attribútumok szerint.

A termékobjektumok további mezőket is tartalmazhatnak az áruház katalógusától, variánsaitól, árazásától és a Shoply konfigurációjától függően. A klienseknek az általuk szükséges mezőket kell használniuk, és biztonságosan figyelmen kívül hagyhatják az ismeretlen mezőket.

Lapozás

Használja a start és limit mezőket további eredmények lekéréséhez. Például miután lekért nyolc terméket start: 0 és limit: 8 értékekkel, a következő oldalt így kérheti le:

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

Álljon meg, amikor a start + docs.length nagyobb vagy egyenlő, mint a num_results, vagy amikor a docs üres.

Csomag- és integrációs megjegyzések

Ha az egyedi storefrontnak beszélgetési funkcióra is szüksége van, adjon chatet egy headless Shopify storefronthoz.

• A standard API-keresés önkiszolgáló módon használható, és nem igényli a helyszíni widgetet.
• A Shopify áruháznak kapcsolódva kell maradnia a Shoply AI-hoz, hogy a termékindexe naprakész maradhasson.
• Az API-keresések és a storefront keresések osztoznak a Shopify csomag havi keresési keretén.
• Tartsa a hívást a backendjén, ha központosítani szeretné a gyorsítótárazást, a naplózást, az újrapróbálkozásokat vagy a hozzáférés-szabályozást.
• Lépjen kapcsolatba velünk Enterprise támogatásért, ha egyedi hitelesítésre, garantált átviteli teljesítményre, SLA-ra, nem Shopify katalógusra vagy a közzétett csomagokon túli limitekre van szüksége.

Ha segítségre van szüksége az áruházkulcs megerősítéséhez vagy egy éles integráció megtervezéséhez, lépjen kapcsolatba a Shoply AI-jal.