Kaip naudoti Shoply AI Search API

Taip. Galite programiškai užklausti Shoply AI Search iš savo vidinės sistemos neįkeldami svetainės valdiklio ir nesiųsdami užklausos per savo Shopify vitrinos puslapį.

Standartinis paieškos API yra prieinamas su kiekvienu Shopify planu, kuriame įtraukta AI Search, įskaitant Forever Free. API užklausos naudoja tą patį mėnesinį paieškų limitą kaip ir paieškos, atliekamos per vitrinos valdiklį. Dabartinius limitus rasite mūsų kainodaros puslapyje.

Jei jums reikia didesnių limitų, paslaugų lygio susitarimo, pasirinktinio duomenų šaltinio arba integracijos, kuri nenaudoja Shoply indeksuoto Shopify katalogo, susisiekite su mumis dėl Enterprise plano.

Prieš pradedant

Įdiekite Shoply AI Shopify parduotuvėje, kurios kataloge norite vykdyti paiešką, ir palaukite, kol bus baigtas pradinis produktų indeksavimas. Jums reikės nuolatinio parduotuvės myshopify.com domeno, pavyzdžiui:

your-store.myshopify.com

API galima kviesti iš bet kurios vidinės sistemos aplinkos. Atskiro API rakto standartiniam produktų paieškos galiniam taškui nereikia, nes jis grąžina tą pačią viešą katalogo informaciją, kurią Shoply gali rodyti vitrinos paieškos patirtyje.

Galinis taškas

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

Užklausos turinys

query yra JSON eilutė užklausos turinyje, o ne įdėtinis JSON objektas. Pavyzdžiui, paieškos frazė waterproof hiking boots siunčiama taip:

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

cURL pavyzdys

Pakeiskite your-store.myshopify.com į nuolatinį savo parduotuvės Shopify domeną:

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 pavyzdys

// 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 pavyzdys

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

Atsakymas

Sėkminga užklausa grąžina:

{
  "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 yra bendras atitinkančių produktų skaičius.
• docs pateikia surikiuotus produktus prašomam puslapiui.
• display_filters pateikia galimus filtrus, tokius kaip kaina, prekės ženklas, spalva ar kiti katalogui būdingi atributai.

Produktų objektuose gali būti papildomų laukų, priklausomai nuo parduotuvės katalogo, variantų, kainodaros ir Shoply konfigūracijos. Klientinės programos turėtų naudoti joms reikalingus laukus ir saugiai ignoruoti nepažįstamus laukus.

Puslapiavimas

Naudokite start ir limit, kad užklaustumėte papildomų rezultatų. Pavyzdžiui, po aštuonių produktų užklausos su start: 0 ir limit: 8, kitą puslapį užklauskite taip:

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

Sustokite, kai start + docs.length yra didesnis arba lygus num_results, arba kai docs yra tuščias.

Pastabos apie planą ir integraciją

Jei jūsų pasirinktinei vitrinai taip pat reikia pokalbio funkcijos, pridėkite pokalbį prie headless Shopify vitrinos.

• Standartinė API paieška yra savitarnos ir nereikalauja svetainės valdiklio.
• Jūsų Shopify parduotuvė turi likti prijungta prie Shoply AI, kad jos produktų indeksas išliktų aktualus.
• API paieškos ir vitrinos paieškos dalijasi mėnesiniu paieškų limitu, taikomu jūsų Shopify planui.
• Palikite šį iškvietimą savo vidinėje sistemoje, jei norite centralizuoti podėlį, žurnalų kaupimą, pakartotinius bandymus ar prieigos kontrolę.
• Susisiekite su mumis dėl Enterprise palaikymo, jei jums reikia pasirinktinio autentifikavimo, garantuoto pralaidumo, SLA, ne-Shopify katalogo ar limitų, viršijančių paskelbtus planus.

Jei reikia pagalbos patvirtinant jūsų parduotuvės raktą arba planuojant produkcinę integraciją, susisiekite su Shoply AI.