Come usare l’API di ricerca AI di Shoply

Sì. Puoi interrogare Shoply AI Search in modo programmatico dal tuo backend senza caricare il widget sul sito né inviare la richiesta tramite la tua vetrina Shopify.

L’API di ricerca standard è disponibile con ogni piano Shopify che include AI Search, incluso Forever Free. Le richieste API utilizzano lo stesso limite mensile di ricerche delle ricerche effettuate tramite il widget della vetrina. Consulta i limiti attuali nella nostra pagina dei prezzi.

Se hai bisogno di limiti più alti, di un accordo sul livello di servizio, di una fonte dati personalizzata o di un’integrazione che non utilizzi un catalogo Shopify indicizzato da Shoply, contattaci per un piano Enterprise.

Prima di iniziare

Installa Shoply AI sul negozio Shopify di cui vuoi cercare il catalogo e attendi il completamento dell’indicizzazione iniziale dei prodotti. Ti servirà il dominio permanente myshopify.com del negozio, ad esempio:

your-store.myshopify.com

L’API può essere chiamata da qualsiasi ambiente backend. Non è necessaria una chiave API separata per l’endpoint standard di ricerca prodotti perché restituisce le stesse informazioni pubbliche del catalogo che Shoply può mostrare nell’esperienza di ricerca della vetrina.

Endpoint

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

Corpo della richiesta

query è una stringa JSON all’interno del corpo della richiesta, non un oggetto JSON annidato. Ad esempio, la frase di ricerca waterproof hiking boots viene inviata come:

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

Esempio cURL

Sostituisci your-store.myshopify.com con il dominio Shopify permanente del tuo negozio:

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
  }'

Esempio JavaScript

// 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);

Esempio Python

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

Risposta

Una richiesta riuscita restituisce:

{
  "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 è il numero totale di prodotti corrispondenti.
• docs contiene i prodotti ordinati per pertinenza per la pagina richiesta.
• display_filters contiene i filtri disponibili come prezzo, brand, colore o altri attributi specifici del catalogo.

Gli oggetti prodotto possono contenere campi aggiuntivi a seconda del catalogo del negozio, delle varianti, dei prezzi e della configurazione di Shoply. I client dovrebbero usare i campi di cui hanno bisogno e ignorare in sicurezza quelli non familiari.

Impaginazione

Usa start e limit per richiedere risultati aggiuntivi. Ad esempio, dopo aver richiesto otto prodotti con start: 0 e limit: 8, richiedi la pagina successiva con:

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

Fermati quando start + docs.length è maggiore o uguale a num_results, oppure quando docs è vuoto.

Note su piano e integrazione

Se la tua vetrina personalizzata ha bisogno anche della conversazione, aggiungi la chat a una vetrina Shopify headless.

• La ricerca API standard è self-service e non richiede il widget sul sito.
• Il tuo negozio Shopify deve rimanere connesso a Shoply AI affinché l’indice prodotti resti aggiornato.
• Le ricerche API e le ricerche nella vetrina condividono il limite mensile di ricerche del tuo piano Shopify.
• Mantieni la chiamata nel tuo backend se vuoi centralizzare cache, logging, retry o controllo degli accessi.
• Contattaci per il supporto Enterprise se hai bisogno di autenticazione personalizzata, throughput garantito, un SLA, un catalogo non Shopify o limiti oltre quelli pubblicati nei piani.

Per assistenza nel confermare la chiave del tuo negozio o nel pianificare un’integrazione in produzione, contatta Shoply AI.