Comment téléverser votre catalogue pour SiteChat

Si vous utilisez SiteChat sur votre propre site web (et non sur une boutique Shopify), vous pouvez envoyer des enregistrements de produits structurés à Shoply afin que les acheteurs puissent les trouver dans le chat SiteChat et dans la recherche de produits.

Ces points de terminaison utilisent le même Settings → Store owner API secret que le reste de la Shoply Merchant API, et la page Product Catalog de l’admin SiteChat peut les appeler avec votre jeton d’accès admin de session connectée. Les boutiques Shopify continuent à synchroniser les données du catalogue via Shopify ; ces routes de téléversement sont disponibles uniquement pour les comptes SiteChat qui ne synchronisent pas déjà un catalogue Magento.

Dans l’admin SiteChat, Product Catalog ouvre une zone de type Shopify avec Products, Collections et Inventory. Vous pouvez ajouter ou modifier des produits, importer des fichiers CSV/Excel, regrouper des produits dans des collections manuelles et ajuster les quantités en stock.

Quelles API sont disponibles ?

Les enregistrements de produit réussis demandent à Shoply de reconstruire l’index de la boutique. Tant que cette reconstruction n’est pas terminée, les réponses indiquent index_status: "pending". Les produits publiés apparaissent ensuite à la fois dans l’index produit et dans la base de connaissances utilisée par le chat SiteChat.

Qui peut utiliser ces API ?

• Votre boutique doit être un compte SiteChat (app_platform vaut SiteChat).
• Les clés de boutique Shopify (y compris tout domaine *.myshopify.com) sont refusées.
• L’authentification doit utiliser soit un secret API propriétaire de boutique valide, soit un jeton d’accès admin SiteChat pour le store_key exact de la requête.
• Les jetons Shopify Admin API ne peuvent pas appeler ces routes.

Créez ou faites tourner le secret propriétaire de la même manière que pour les autres intégrations Merchant API : How to Use the Shoply Merchant API. Dans la console d’administration SiteChat, ouvrez Product Catalog pour gérer les produits, les collections et l’inventaire — ou importer un fichier CSV ou Excel — sans gérer vous-même le secret.

Comment fonctionne l’authentification ?

Depuis un connecteur serveur

Appelez l’API depuis un backend de confiance via HTTPS. Placez une chaîne JSON dans l’en-tête Authorization :

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete est le nom de champ public, y compris son orthographe historique. store_owner_api_secret est également accepté. Il ne s’agit pas d’un jeton Bearer.

Depuis l’admin SiteChat

La page Product Catalog envoie à la place votre session admin connectée :

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "admin_auth_token": "YOUR_SITECHAT_ACCESS_TOKEN"
}

access_token est accepté comme alias de admin_auth_token.

Le paramètre de requête store_key doit correspondre à l’en-tête. Conservez les secrets propriétaires uniquement dans des variables d’environnement côté serveur — jamais dans un script storefront, une URL ou un dépôt public.

export SHOPLY_STORE_KEY="your-sitechat-store-key"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

Comment téléverser des produits ?

POST https://api.shoplyai.ai/merchant/products/batch?store_key=YOUR_SITECHAT_STORE_KEY

{
  "source": "woocommerce-main",
  "products": [
    {
      "external_id": "123",
      "title": "Trail shoes",
      "description": "Water-resistant hiking shoes.",
      "url": "https://example.com/products/trail-shoes",
      "currency": "USD",
      "price": "49.95",
      "original_price": "59.95",
      "available": true,
      "status": "published",
      "images": ["https://example.com/images/trail-shoes.jpg"],
      "categories": ["Footwear"],
      "metafields": {"material": "Leather"},
      "variants": [
        {
          "external_id": "124",
          "title": "Brown / 42",
          "sku": "TRAIL-BR-42",
          "price": "49.95",
          "available": true,
          "metafields": {"color": "Brown", "size": "42"}
        }
      ]
    }
  ]
}

Champs obligatoires et règles

• Champs produit obligatoires : external_id, title, url, currency, price et available. status vaut par défaut published.
• Inventaire facultatif : définissez tracks_inventory sur true et une quantity non négative sur le produit ou la variante. Shoply déduit alors la disponibilité à partir du stock (quantity > 0) et enregistre total_inventory pour les listes admin.
• source nomme la connexion au catalogue (pas nécessairement une plateforme). Utilisez un nom stable comme woocommerce-main. Caractères autorisés : lettres minuscules, chiffres, underscores et tirets ; jusqu’à 64 caractères. Les produits créés par formulaire dans l’admin utilisent par défaut la source admin.
• L’identité du produit est la combinaison de la boutique, de la source et de l’ID externe. Les opérations d’upsert POST par lot et unitaires sont des remplacements complets, et non des patchs : les champs facultatifs omis sont effacés. Utilisez PATCH pour les mises à jour partielles.
• Les lots contiennent de 1 à 50 produits et au maximum 2 000 000 octets de requête. Le JSON validé de chaque produit est limité à 128 000 octets, avec au plus 250 variantes.
• Préférez les chaînes décimales pour les prix. La devise est un code majuscule à trois lettres.
• Les URL de produit et d’image doivent être en HTTP(S). L’importation ne récupère pas ces URL pour vous.
• Utilisez les metafields publics pour les spécifications de produit recherchables (l’équivalent SiteChat des métachamps produit Shopify). Les valeurs doivent être de simples chaînes. L’ancien champ attributes est accepté comme alias. Le champ privé metadata des produits n’est plus pris en charge.
• Les produits draft et archived sont exclus du prochain index publié. Les produits publiés en rupture de stock restent indexés avec leur disponibilité associée.
• Les collections manuelles enregistrent un titre, une description, un statut et une liste d’appartenances de produits (source + external_id). Les collections intelligentes/basées sur des règles ne sont pas prises en charge dans cette version.

Exemple de réponse de succès

{
  "results": [
    {
      "external_id": "123",
      "product_id": "sitechat_product::woocommerce-main::<sha256-of-external-id>",
      "status": "stored"
    }
  ],
  "index_status": "pending",
  "index_revision": 1
}

Shoply valide l’ensemble de la requête avant d’écrire. Un HTTP 200 peut tout de même lister certains résultats failed avec error: "storage_error". Inspectez chaque résultat et réessayez les produits en échec. Si index_status vaut request_failed, le stockage a réussi mais l’indexation n’a pas été planifiée — réessayez également les produits stockés.

Exemple Python

import json
import os
import requests
 
store_key = os.environ["SHOPLY_STORE_KEY"]
headers = {
    "Authorization": json.dumps({
        "store_key": store_key,
        "store_owner_api_secrete": os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
    })
}
 
response = requests.post(
    "https://api.shoplyai.ai/merchant/products/batch",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "custom",
        "products": [{
            "external_id": "123",
            "title": "Trail shoes",
            "url": "https://example.com/products/trail-shoes",
            "currency": "USD",
            "price": "49.95",
            "available": True,
        }],
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
failed = [item["external_id"] for item in result["results"] if item["status"] != "stored"]
if failed:
    raise RuntimeError(f"Products need retry: {failed}")
if result["index_status"] == "request_failed":
    raise RuntimeError("Products saved, but retry the batch to request indexing")

Comment vérifier un produit importé ?

GET https://api.shoplyai.ai/merchant/products?store_key=YOUR_SITECHAT_STORE_KEY&source=woocommerce-main&external_id=123

Utilisez le même en-tête Authorization. La réponse inclut schema_version, updated_at, index_status et le product normalisé. Les enregistrements manquants renvoient HTTP 404.

Après qu’une reconstruction est publiée par l’indexeur en arrière-plan, le statut de relecture par produit devient indexed, excluded (pour les produits en brouillon ou archivés) ou limit_exceeded. Utilisez GET /merchant/products/list pour le listing admin. Archivez de manière logicielle avec DELETE /merchant/products (ou définissez status sur archived / draft) pour garder un produit hors du prochain index publié ; il n’existe pas de suppression définitive dans cette version.

record = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={
        "store_key": store_key,
        "source": "woocommerce-main",
        "external_id": "123",
    },
    headers=headers,
    timeout=30,
)
record.raise_for_status()
print(record.json()["index_status"], record.json()["product"]["title"])

Puis-je téléverser des images de produits ?

Oui. Si une image est déjà disponible à une URL HTTPS publique durable, placez cette URL dans la liste images du produit ou dans le champ image d’une variante. Les URL HTTPS publiques S3 fonctionnent. Les chemins bruts s3:// et les URL signées de courte durée ne fonctionnent pas.

Pour que Shoply héberge le fichier, téléversez les octets bruts de l’image depuis votre backend :

POST https://api.shoplyai.ai/merchant/products/images?store_key=YOUR_SITECHAT_STORE_KEY
Content-Type: image/png

Envoyez les octets bruts du fichier, et non du JSON, du base64 ou des données de formulaire multipart. Les formats JPEG, PNG et WebP sont acceptés, jusqu’à 10 Mio et 20 millions de pixels. Les images animées ne sont pas prises en charge. Shoply convertit l’image en WebP et supprime les métadonnées intégrées.

with open("trail-shoes.png", "rb") as image_file:
    response = requests.post(
        "https://api.shoplyai.ai/merchant/products/images",
        params={"store_key": store_key},
        headers={**headers, "Content-Type": "image/png"},
        data=image_file,
        timeout=60,
    )
response.raise_for_status()
image_url = response.json()["url"]

HTTP 201 renvoie url, content_type, size_bytes, width et height. Le téléversement d’une image seule ne l’attache pas à un produit et ne demande pas d’indexation. Incluez l’URL renvoyée dans un produit complet et soumettez-le à nouveau via /merchant/products/batch.

La même image téléversée à nouveau pour le même compte réutilise son URL. Une image modifiée reçoit une nouvelle URL. Il n’existe pas de point de terminaison de suppression d’image dans cette version.

Quand les produits apparaissent-ils dans le chat et la recherche ?

Après un enregistrement par lot réussi, Shoply demande une reconstruction d’index en arrière-plan. Les réponses indiquent index_status: "pending" jusqu’à ce que le worker publie le nouvel index. Il n’existe aucune garantie de délai d’achèvement fixe.

• Les produits publiés entrent à la fois dans la recherche de produits et dans la base de connaissances utilisée par le chat SiteChat.
• Les produits en brouillon et archivés sont exclus lors de la reconstruction suivante.
• Si l’indexation n’a pas été planifiée (index_status: "request_failed"), réessayez le lot pour les produits déjà stockés avec succès.

À quelles erreurs dois-je m’attendre ?

Les secrets expirent après 90 jours. Créez un remplacement dans Settings → Store owner API secret avant l’expiration, et révoquez tout secret dont vous n’avez plus besoin. Le même secret peut également appeler les points de terminaison d’analytics, de conversation et de connaissance documentés dans le guide Merchant API.

Pour obtenir de l’aide sur une intégration, contactez Shoply AI.