Slik bruker du Shoply AI Search API

Ja. Du kan sende spørringer til Shoply AI Search programmatisk fra din egen backend uten å laste inn widgeten på nettstedet eller sende forespørselen gjennom Shopify-butikkfronten din.

Standard søke-API er tilgjengelig med alle Shopify-abonnementer som inkluderer AI Search, inkludert Forever Free. API-forespørsler bruker den samme månedlige søkekvoten som søk utført gjennom widgeten i butikkfronten. Se gjeldende grenser på vår prisside.

Hvis du trenger høyere grenser, en tjenestenivåavtale, en tilpasset datakilde eller en integrasjon som ikke bruker en Shopify-katalog indeksert av Shoply, kontakt oss om et Enterprise-abonnement.

Før du starter

Installer Shoply AI i Shopify-butikken med katalogen du vil søke i, og la den første produktindekseringen fullføres. Du trenger butikkens permanente myshopify.com-domene, for eksempel:

your-store.myshopify.com

API-et kan kalles fra ethvert backend-miljø. En separat API-nøkkel er ikke nødvendig for standard endepunkt for produktsøk, fordi det returnerer den samme offentlige kataloginformasjonen som Shoply kan vise i søkeopplevelsen i butikkfronten.

Endepunkt

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

Forespørselskropp

query er en JSON-streng inne i forespørselskroppen, ikke et nøstet JSON-objekt. For eksempel sendes søkefrasen waterproof hiking boots som:

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

cURL-eksempel

Erstatt your-store.myshopify.com med butikkens permanente Shopify-domene:

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

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

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

Respons

En vellykket forespørsel returnerer:

{
  "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 er det totale antallet samsvarende produkter.
• docs inneholder de rangerte produktene for den forespurte siden.
• display_filters inneholder tilgjengelige filtre som pris, merke, farge eller andre katalogspesifikke attributter.

Produktobjekter kan inneholde flere felter avhengig av butikkens katalog, varianter, priser og Shoply-konfigurasjon. Klienter bør bruke feltene de trenger og trygt ignorere ukjente felter.

Paginering

Bruk start og limit for å be om flere resultater. For eksempel, etter å ha bedt om åtte produkter med start: 0 og limit: 8, kan du be om neste side med:

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

Stopp når start + docs.length er større enn eller lik num_results, eller når docs er tom.

Merknader om abonnement og integrasjon

Hvis den tilpassede butikkfronten din også trenger samtaler, legg til chat i en headless Shopify-butikkfront.

• Standard API-søk er selvbetjent og krever ikke widgeten på nettstedet.
• Shopify-butikken din må forbli koblet til Shoply AI slik at produktindeksen kan holdes oppdatert.
• API-søk og søk i butikkfronten deler den månedlige søkekvoten for Shopify-abonnementet ditt.
• Behold kallene i backend hvis du vil sentralisere caching, logging, forsøk på nytt eller tilgangskontroll.
• Kontakt oss for Enterprise-støtte hvis du trenger tilpasset autentisering, garantert gjennomstrømning, en SLA, en katalog som ikke er fra Shopify, eller grenser utover de publiserte abonnementene.

For hjelp med å bekrefte butikkens nøkkel eller planlegge en produksjonsintegrasjon, kontakt Shoply AI.