Hoe u uw catalogus uploadt voor SiteChat

Als u SiteChat op uw eigen website gebruikt (niet een Shopify-winkel), kunt u gestructureerde productrecords naar Shoply sturen zodat shoppers ze kunnen vinden in SiteChat-chat en productzoekopdrachten.

Deze endpoints gebruiken dezelfde Settings → Store owner API secret als de rest van de Shoply Merchant API, en de SiteChat-beheerpagina Product Catalog kan ze aanroepen met uw admin-toegangstoken terwijl u bent ingelogd. Shopify-winkels blijven catalogusgegevens synchroniseren via Shopify; deze uploadroutes zijn alleen beschikbaar voor SiteChat-accounts die nog geen Magento-catalogus synchroniseren.

In de SiteChat-admin opent Product Catalog een Shopify-achtige omgeving met Products, Collections en Inventory. U kunt producten toevoegen of bewerken, CSV/Excel importeren, producten groeperen in handmatige collecties en voorraadhoeveelheden aanpassen.

Welke API’s zijn beschikbaar?

Succesvolle productopslagen vragen Shoply om de winkelindex opnieuw op te bouwen. Totdat die herbouw is voltooid, melden responses index_status: "pending". Gepubliceerde producten verschijnen daarna zowel in de productindex als in de kennis die door SiteChat-chat wordt gebruikt.

Wie kan deze API’s gebruiken?

• Uw winkel moet een SiteChat-account zijn (app_platform is SiteChat).
• Shopify-winkelsleutels (inclusief elk *.myshopify.com-domein) worden afgewezen.
• Authenticatie moet gebeuren met ofwel een geldige API-secret voor winkeleigenaren of een SiteChat admin-toegangstoken voor exact de store_key in de aanvraag.
• Shopify Admin API-tokens kunnen deze routes niet aanroepen.

Maak of roteer de owner secret op dezelfde manier als andere Merchant API-integraties: Hoe u de Shoply Merchant API gebruikt. Open in de SiteChat-adminconsole Product Catalog om producten, collecties en voorraad te beheren — of een CSV- of Excel-bestand te importeren — zonder de secret zelf te hoeven beheren.

Hoe werkt authenticatie?

Vanuit een serverconnector

Roep de API aan vanaf een vertrouwde backend via HTTPS. Zet een JSON-string in de Authorization-header:

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

store_owner_api_secrete is de publieke veldnaam, inclusief de historische spelling. store_owner_api_secret wordt ook geaccepteerd. Dit is geen Bearer-token.

Vanuit de SiteChat-admin

De pagina Product Catalog verstuurt in plaats daarvan uw adminsessie terwijl u bent ingelogd:

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

access_token wordt geaccepteerd als alias voor admin_auth_token.

De queryparameter store_key moet overeenkomen met de header. Bewaar owner secrets alleen in server-side omgevingsvariabelen — nooit in een storefront-script, URL of openbare repository.

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

Hoe upload ik producten?

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

Vereiste velden en regels

• Vereiste productvelden: external_id, title, url, currency, price en available. status is standaard published.
• Optionele voorraadtracking: stel tracks_inventory in op true en een niet-negatieve quantity op het product of de variant. Shoply leidt dan beschikbaarheid af uit voorraad (quantity > 0) en slaat total_inventory op voor adminlijsten.
• source benoemt de catalogusverbinding (niet noodzakelijk een platform). Gebruik een stabiele naam zoals woocommerce-main. Toegestane tekens: kleine letters, cijfers, underscores en koppeltekens; maximaal 64 tekens. Producten die via formulieren in admin zijn aangemaakt, hebben standaard source admin.
• Productidentiteit is de combinatie van winkel, source en external ID. Batch- en enkelvoudige POST-upserts zijn volledige vervangingen, geen patches: weggelaten optionele velden worden gewist. Gebruik PATCH voor gedeeltelijke updates.
• Batches bevatten 1–50 producten en maximaal 2.000.000 request-bytes. De gevalideerde JSON van elk product is beperkt tot 128.000 bytes, met maximaal 250 varianten.
• Gebruik bij voorkeur decimale strings voor prijzen. Valuta is een uppercase code van drie letters.
• Product- en afbeeldings-URL’s moeten HTTP(S) zijn. Importeren haalt deze URL’s niet voor u op.
• Gebruik openbare metafields voor doorzoekbare productspecificaties (het SiteChat-equivalent van Shopify-productmetafields). Waarden moeten platte strings zijn. Verouderde attributes wordt geaccepteerd als alias. Privé-product-metadata wordt niet langer ondersteund.
• draft- en archived-producten worden uit de volgende gepubliceerde index gehouden. Uitverkochte gepubliceerde producten blijven geïndexeerd met beschikbaarheid eraan gekoppeld.
• Handmatige collecties slaan een titel, beschrijving, status en een lijst van productlidmaatschappen op (source + external_id). Slimme/op regels gebaseerde collecties worden in deze release niet ondersteund.

Voorbeeld van een succesvolle response

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

Shoply valideert de volledige aanvraag voordat er wordt geschreven. Een HTTP 200 kan nog steeds enkele failed-resultaten bevatten met error: "storage_error". Controleer elk resultaat en probeer mislukte producten opnieuw. Als index_status request_failed is, is opslag geslaagd maar is indexering niet ingepland — probeer de opgeslagen producten dan ook opnieuw.

Python-voorbeeld

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

Hoe verifieer ik een geïmporteerd product?

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

Gebruik dezelfde Authorization-header. De response bevat schema_version, updated_at, index_status en het genormaliseerde product. Ontbrekende records geven HTTP 404 terug.

Nadat de achtergrondindexeerder een herbouw heeft gepubliceerd, wordt de uitleesstatus per product indexed, excluded (voor draft- of archived-producten) of limit_exceeded. Gebruik GET /merchant/products/list voor admin-overzichten. Soft-archiveer met DELETE /merchant/products (of zet status op archived / draft) om een product uit de volgende gepubliceerde index te houden; er is in deze release geen hard-delete.

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

Hoe werk ik varianten of metafields veilig bij?

Voor een PATCH die variants, metafields of het verouderde veld attributes bevat, leest u eerst het product met GET. Bouw de wijziging op basis van die response en neem de top-level updated_at-waarde ervan op als expected_updated_at in de PATCH-body. Dit geldt ook wanneer u varianten of metafields wist.

current_response = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key, "source": "woocommerce-main", "external_id": "123"},
    headers=headers,
    timeout=30,
)
current_response.raise_for_status()
current = current_response.json()
updated_metafields = {**current["product"].get("metafields", {}), "material": "Leather"}
response = requests.patch(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "woocommerce-main",
        "external_id": "123",
        "expected_updated_at": current["updated_at"],
        "metafields": updated_metafields,
    },
    timeout=30,
)
response.raise_for_status()

HTTP 409 betekent dat de versie ontbrak of dat een andere update het product heeft gewijzigd. Lees het nieuwste product en voeg uw beoogde wijzigingen opnieuw samen voordat u het opnieuw probeert. Koppel geen nieuwe versie aan een oude variantenlijst: dat kan nieuwere voorraadwaarden overschrijven.

Bestaande integraties die deze velden PATCHEN zonder versie moeten worden bijgewerkt. PATCH-verzoeken met alleen scalaire waarden, toegewezen voorraadaanpassingen en volledige vervangingen via POST of batchimport vereisen dit veld niet. Volledige vervangingen vervangen nog steeds het volledige product.

Kan ik productafbeeldingen uploaden?

Ja. Als een afbeelding al beschikbaar is op een blijvende openbare HTTPS-URL, zet die URL dan in de images-lijst van het product of in het image-veld van een variant. Openbare S3 HTTPS-URL’s werken. Ruwe s3://-paden en kortdurende ondertekende URL’s niet.

Om Shoply het bestand te laten hosten, uploadt u ruwe afbeeldingsbytes vanaf uw backend:

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

Stuur de ruwe bestandsbytes, geen JSON, base64 of multipart form data. JPEG, PNG en WebP worden geaccepteerd, tot 10 MiB en 20 miljoen pixels. Geanimeerde afbeeldingen worden niet ondersteund. Shoply converteert de afbeelding naar WebP en verwijdert ingesloten metadata.

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 retourneert url, content_type, size_bytes, width en height. Alleen een afbeelding uploaden koppelt die niet aan een product en vraagt geen indexering aan. Neem de geretourneerde URL op in een volledig product en dien het opnieuw in via /merchant/products/batch.

Dezelfde afbeelding die opnieuw voor hetzelfde account wordt geüpload, hergebruikt zijn URL. Een gewijzigde afbeelding krijgt een nieuwe URL. Er is in deze release geen endpoint om afbeeldingen te verwijderen.

Wanneer verschijnen producten in chat en zoeken?

Na een succesvolle batch-opslag vraagt Shoply een herbouw van de achtergrondindex aan. Responses melden index_status: "pending" totdat de worker de nieuwe index publiceert. Er is geen vaste garantie voor de voltooiingstijd.

• Gepubliceerde producten komen terecht in zowel productzoekopdrachten als de kennis die door SiteChat-chat wordt gebruikt.
• Draft- en archived-producten worden uitgesloten bij de volgende herbouw.
• Als indexering niet is ingepland (index_status: "request_failed"), probeer de batch dan opnieuw voor de producten die al succesvol zijn opgeslagen.

Welke fouten kan ik verwachten?

Secrets verlopen na 90 dagen. Maak vóór het verlopen een vervanging aan in Settings → Store owner API secret, en trek elke secret in die u niet langer nodig hebt. Dezelfde secret kan ook analytics-, conversation- en knowledge-endpoints aanroepen die zijn gedocumenteerd in de Merchant API guide.

Voor hulp bij een integratie, neem contact op met Shoply AI.