Shoply AI Search API:n käyttö

Kyllä. Voit tehdä Shoply AI Search -hakuja ohjelmallisesti omasta taustajärjestelmästäsi ilman, että lataat sivustolla näkyvän widgetin tai lähetät pyynnön Shopify-julkisivusi kautta.

Tavallinen Search API on saatavilla kaikissa Shopify-paketeissa, joihin sisältyy AI Search, mukaan lukien Forever Free. API-pyynnöt käyttävät samaa kuukausittaista hakukiintiötä kuin julkisivun widgetin kautta tehdyt haut. Katso ajantasaiset rajat hinnoittelusivultamme.

Jos tarvitset suuremmat rajat, palvelutasosopimuksen, mukautetun tietolähteen tai integraation, joka ei käytä Shoplyn indeksoimaa Shopify-katalogia, ota yhteyttä Enterprise-paketista.

Ennen kuin aloitat

Asenna Shoply AI siihen Shopify-kauppaan, jonka katalogista haluat hakea, ja anna alkuperäisen tuoteindeksoinnin valmistua. Tarvitset kaupan pysyvän myshopify.com-verkkotunnuksen, esimerkiksi:

your-store.myshopify.com

API:a voidaan kutsua mistä tahansa taustajärjestelmäympäristöstä. Erillistä API-avainta ei tarvita tavalliseen tuotehakuendpointiin, koska se palauttaa samat julkiset katalogitiedot, jotka Shoply voi näyttää julkisivun hakukokemuksessa.

Endpoint

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

Pyynnön runko

query on JSON-merkkijono pyynnön rungon sisällä, ei sisäkkäinen JSON-objekti. Esimerkiksi hakulauseke waterproof hiking boots lähetetään näin:

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

cURL-esimerkki

Korvaa your-store.myshopify.com kauppasi pysyvällä Shopify-verkkotunnuksella:

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-esimerkki

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

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

Vastaus

Onnistunut pyyntö palauttaa:

{
  "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 on osuvien tuotteiden kokonaismäärä.
• docs sisältää pyydetyn sivun järjestetyt tuotteet.
• display_filters sisältää saatavilla olevat suodattimet, kuten hinnan, brändin, värin tai muut katalogikohtaiset ominaisuudet.

Tuoteobjektit voivat sisältää lisäkenttiä kaupan katalogin, varianttien, hinnoittelun ja Shoply-konfiguraation mukaan. Asiakassovellusten kannattaa käyttää tarvitsemiaan kenttiä ja ohittaa turvallisesti tuntemattomat kentät.

Sivutus

Käytä start- ja limit-kenttiä pyytääksesi lisää tuloksia. Esimerkiksi pyydettyäsi kahdeksan tuotetta arvoilla start: 0 ja limit: 8, pyydä seuraava sivu näin:

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

Lopeta, kun start + docs.length on suurempi tai yhtä suuri kuin num_results, tai kun docs on tyhjä.

Paketti- ja integraatiohuomiot

Jos mukautettu julkisivusi tarvitsee myös keskustelutoiminnon, lisää chat headless Shopify -julkisivuun.

• Tavallinen API-haku on itsepalvelu eikä vaadi sivustolla näkyvää widgetiä.
• Shopify-kauppasi on pysyttävä yhdistettynä Shoply AI:hin, jotta sen tuoteindeksi pysyy ajan tasalla.
• API-haut ja julkisivuhaut jakavat Shopify-pakettisi kuukausittaisen hakukiintiön.
• Pidä kutsu taustajärjestelmässäsi, jos haluat keskittää välimuistin, lokituksen, uudelleenyritykset tai käyttöoikeuksien hallinnan.
• Ota yhteyttä Enterprise-tukeen, jos tarvitset mukautetun todennuksen, taatun läpimenon, SLA:n, muun kuin Shopify-katalogin tai julkaistut paketit ylittävät rajat.

Jos tarvitset apua kauppasi avaimen varmistamisessa tai tuotantointegraation suunnittelussa, ota yhteyttä Shoply AI:hin.