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 Instellingen → Store owner API secret als de rest van de Shoply Merchant API, en de pagina Product Catalog in de SiteChat-beheeromgeving kan ze aanroepen met uw beheerderstoegangstoken terwijl u bent ingelogd. Shopify-winkels blijven catalogusgegevens synchroniseren via Shopify; deze uploadroutes zijn alleen beschikbaar voor SiteChat-accounts die niet al een Magento-catalogus synchroniseren.

In de SiteChat-beheeromgeving opent Product Catalog een gebied in Shopify-stijl 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 heropbouw is voltooid, rapporteren 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).
• Sleutels van Shopify-winkels (inclusief elk *.myshopify.com-domein) worden geweigerd.
• Authenticatie moet ofwel een geldig API-geheim van de winkeleigenaar gebruiken, of een SiteChat-beheerderstoegangstoken voor exact de store_key in de aanvraag.
• Shopify Admin API-tokens kunnen deze routes niet aanroepen.

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

Hoe werkt authenticatie?

Vanuit een serverconnector

Roep de API aan vanuit een vertrouwde backend via HTTPS. Plaats 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 openbare veldnaam, inclusief de historische spelling. store_owner_api_secret wordt ook geaccepteerd. Dit is geen Bearer-token.

Vanuit de SiteChat-beheeromgeving

De pagina Product Catalog verzendt in plaats daarvan uw ingelogde beheerderssessie:

{
  "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 eigenaargeheimen alleen in omgevingsvariabelen aan de serverzijde — 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"}
        }
      ]
    }
  ]
}

Verplichte velden en regels

• Verplichte productvelden: external_id, title, url, currency, price en available. status wordt standaard published.
• Optionele voorraad: 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 beheerlijsten.
• 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 in de beheeromgeving zijn aangemaakt krijgen 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 aanvraagbytes. De gevalideerde JSON van elk product is beperkt tot 128.000 bytes, met maximaal 250 varianten.
• Geef voor prijzen bij voorkeur decimale strings op. Valuta is een uppercase code van drie letters.
• Product- en afbeeldings-URL’s moeten HTTP(S) zijn. Importeren haalt die URL’s niet voor u op.
• Gebruik openbare metafields voor doorzoekbare productspecificaties (het equivalent van SiteChat voor Shopify-productmetavelden). 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 gelaten. Uitverkochte gepubliceerde producten blijven geïndexeerd met beschikbaarheid erbij.
• Handmatige collecties slaan een titel, beschrijving, status en een lijst met productlidmaatschappen op (source + external_id). Slimme/regelgebaseerde 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 controleer 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 retourneren HTTP 404.

Nadat de achtergrondindexeerder een heropbouw heeft gepubliceerd, wordt de terugleesstatus per product indexed, excluded (voor concept- of gearchiveerde producten) of limit_exceeded. Gebruik GET /merchant/products/list voor beheerweergaven. Archiveer zacht met DELETE /merchant/products (of stel status in 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"])

Kan ik productafbeeldingen uploaden?

Ja. Als een afbeelding al beschikbaar is via een blijvende openbare HTTPS-URL, zet die URL dan in de productlijst images of in het veld image 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 vanuit uw backend:

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

Verzend 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 deze 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 batchopslag vraagt Shoply een achtergrond-heropbouw van de index aan. Responses rapporteren index_status: "pending" totdat de worker de nieuwe index publiceert. Er is geen vaste garantie voor de voltooiingstijd.

• Gepubliceerde producten komen zowel in productzoekopdrachten als in de kennis die door SiteChat-chat wordt gebruikt.
• Concept- en gearchiveerde producten worden uitgesloten bij de volgende heropbouw.
• 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?

Geheimen verlopen na 90 dagen. Maak vóór de vervaldatum een vervanging aan in Instellingen → Store owner API secret, en trek elk geheim in dat u niet langer nodig hebt. Hetzelfde geheim kan ook analytics-, conversatie- en knowledge-endpoints aanroepen die zijn gedocumenteerd in de Merchant API-handleiding.

Voor hulp bij een integratie kunt u contact opnemen met Shoply AI.