Comment utiliser l’API de recherche Shoply AI

Oui. Vous pouvez interroger Shoply AI Search par programmation depuis votre propre backend sans charger le widget sur site ni envoyer la requête via votre vitrine Shopify.

L’API de recherche standard est disponible avec tous les forfaits Shopify qui incluent AI Search, y compris Forever Free. Les requêtes API utilisent la même allocation mensuelle de recherches que les recherches effectuées via le widget de la vitrine. Consultez les limites actuelles sur notre page des tarifs.

Si vous avez besoin de limites plus élevées, d’un accord de niveau de service, d’une source de données personnalisée ou d’une intégration qui n’utilise pas un catalogue Shopify indexé par Shoply, contactez-nous au sujet d’un forfait Enterprise.

Avant de commencer

Installez Shoply AI sur la boutique Shopify dont vous souhaitez interroger le catalogue et laissez l’indexation initiale des produits se terminer. Vous aurez besoin du domaine permanent myshopify.com de la boutique, par exemple :

your-store.myshopify.com

L’API peut être appelée depuis n’importe quel environnement backend. Une clé API distincte n’est pas nécessaire pour le point de terminaison standard de recherche de produits, car il renvoie les mêmes informations de catalogue public que Shoply peut afficher dans l’expérience de recherche de la vitrine.

Point de terminaison

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

Corps de la requête

query est une chaîne JSON à l’intérieur du corps de la requête, et non un objet JSON imbriqué. Par exemple, l’expression de recherche waterproof hiking boots est envoyée ainsi :

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

Exemple cURL

Remplacez your-store.myshopify.com par le domaine Shopify permanent de votre boutique :

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

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

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

Réponse

Une requête réussie renvoie :

{
  "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 correspond au nombre total de produits correspondants.
• docs contient les produits classés pour la page demandée.
• display_filters contient les filtres disponibles, comme le prix, la marque, la couleur ou d’autres attributs propres au catalogue.

Les objets produit peuvent contenir des champs supplémentaires selon le catalogue de la boutique, les variantes, la tarification et la configuration de Shoply. Les clients doivent utiliser les champs dont ils ont besoin et ignorer sans risque les champs non familiers.

Pagination

Utilisez start et limit pour demander des résultats supplémentaires. Par exemple, après avoir demandé huit produits avec start: 0 et limit: 8, demandez la page suivante avec :

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

Arrêtez lorsque start + docs.length est supérieur ou égal à num_results, ou lorsque docs est vide.

Remarques sur les forfaits et l’intégration

Si votre vitrine personnalisée a aussi besoin de conversation, ajoutez le chat à une vitrine Shopify headless.

• La recherche API standard est en libre-service et ne nécessite pas le widget sur site.
• Votre boutique Shopify doit rester connectée à Shoply AI afin que son index de produits reste à jour.
• Les recherches API et les recherches de la vitrine partagent l’allocation mensuelle de recherches de votre forfait Shopify.
• Conservez l’appel sur votre backend si vous souhaitez centraliser la mise en cache, la journalisation, les nouvelles tentatives ou le contrôle d’accès.
• Contactez-nous pour une assistance Enterprise si vous avez besoin d’une authentification personnalisée, d’un débit garanti, d’un SLA, d’un catalogue non Shopify ou de limites au-delà des forfaits publiés.

Pour obtenir de l’aide afin de confirmer votre clé de boutique ou de planifier une intégration en production, contactez Shoply AI.