Sådan bruger du Shoply AI Search API

Ja. Du kan forespørge Shoply AI Search programmæssigt fra din egen backend uden at indlæse widgetten på siden eller sende requesten gennem din Shopify-storefront.

Det standardmæssige search API er tilgængeligt med alle Shopify-abonnementer, der inkluderer AI Search, herunder Forever Free. API-requests bruger den samme månedlige søgekvote som søgninger, der foretages gennem storefront-widgetten. Se de aktuelle grænser på vores prisside.

Hvis du har brug for højere grænser, en service level agreement, en tilpasset datakilde eller en integration, der ikke bruger et Shoply-indekseret Shopify-katalog, kontakt os om et Enterprise-abonnement.

Før du går i gang

Installer Shoply AI på den Shopify-butik, hvis katalog du vil søge i, og lad den indledende produktindeksering blive færdig. Du skal bruge butikkens permanente myshopify.com-domæne, såsom:

your-store.myshopify.com

API’et kan kaldes fra ethvert backend-miljø. En separat API-nøgle er ikke påkrævet for standard-endpointet til produktsøgning, fordi det returnerer de samme offentlige katalogoplysninger, som Shoply kan vise i storefront-søgeoplevelsen.

Endpoint

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

Request body

query er en JSON-streng inde i request body, ikke et indlejret JSON-objekt. For eksempel sendes søgefrasen waterproof hiking boots som:

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

cURL-eksempel

Erstat your-store.myshopify.com med din butiks permanente Shopify-domæne:

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 request 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 samlede antal matchende produkter.
• docs indeholder de rangerede produkter for den anmodede side.
• display_filters indeholder tilgængelige filtre såsom pris, brand, farve eller andre katalogspecifikke attributter.

Produktobjekter kan indeholde yderligere felter afhængigt af butikkens katalog, varianter, priser og Shoply-konfiguration. Klienter bør bruge de felter, de har brug for, og trygt ignorere ukendte felter.

Paginering

Brug start og limit til at anmode om flere resultater. For eksempel, efter at have anmodet om otte produkter med start: 0 og limit: 8, anmod om den næste side med:

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

Stop, når start + docs.length er større end eller lig med num_results, eller når docs er tom.

Bemærkninger om abonnement og integration

Hvis din tilpassede storefront også har brug for samtale, kan du tilføje chat til en headless Shopify-storefront.

• Standard API-søgning er self-service og kræver ikke widgetten på siden.
• Din Shopify-butik skal forblive forbundet til Shoply AI, så dens produktindeks kan holdes opdateret.
• API-søgninger og storefront-søgninger deler den månedlige søgekvote for dit Shopify-abonnement.
• Bevar kaldet på din backend, hvis du vil centralisere caching, logging, retries eller adgangskontrol.
• Kontakt os for Enterprise-support, hvis du har brug for tilpasset autentificering, garanteret throughput, en SLA, et ikke-Shopify-katalog eller grænser ud over de offentliggjorte abonnementer.

Hvis du har brug for hjælp til at bekræfte din store key eller planlægge en produktionsintegration, kontakt Shoply AI.