So laden Sie Ihren Katalog für SiteChat hoch

Wenn Sie SiteChat auf Ihrer eigenen Website verwenden (nicht in einem Shopify-Shop), können Sie strukturierte Produktdatensätze an Shoply senden, damit Kund:innen sie im SiteChat-Chat und in der Produktsuche finden können.

Diese Endpunkte verwenden dasselbe Einstellungen → API-Geheimnis des Store-Inhabers wie der Rest der Shoply Merchant API, und die SiteChat-Adminseite Product Catalog kann sie mit Ihrem Admin-Zugriffstoken der angemeldeten Sitzung aufrufen. Shopify-Shops synchronisieren Katalogdaten weiterhin über Shopify; diese Upload-Routen sind nur für SiteChat-Konten verfügbar, die nicht bereits einen Magento-Katalog synchronisieren.

Im SiteChat-Adminbereich öffnet Product Catalog einen Bereich im Shopify-Stil mit Products, Collections und Inventory. Sie können Produkte hinzufügen oder bearbeiten, CSV/Excel importieren, Produkte in manuellen Collections gruppieren und Lagerbestände anpassen.

Welche APIs sind verfügbar?

Erfolgreiche Produktspeicherungen veranlassen Shoply, den Store-Index neu aufzubauen. Bis dieser Neuaufbau abgeschlossen ist, melden Antworten index_status: "pending". Veröffentlichte Produkte erscheinen dann sowohl im Produktindex als auch in dem Wissen, das vom SiteChat-Chat verwendet wird.

Wer kann diese APIs verwenden?

• Ihr Store muss ein SiteChat-Konto sein (app_platform ist SiteChat).
• Shopify-Store-Schlüssel (einschließlich jeder *.myshopify.com-Domain) werden abgelehnt.
• Die Authentifizierung muss entweder ein gültiges API-Geheimnis des Store-Inhabers oder ein SiteChat-Admin-Zugriffstoken für genau den store_key in der Anfrage verwenden.
• Shopify-Admin-API-Tokens können diese Routen nicht aufrufen.

Erstellen oder rotieren Sie das Inhaber-Geheimnis auf dieselbe Weise wie bei anderen Merchant-API-Integrationen: So verwenden Sie die Shoply Merchant API. Öffnen Sie in der SiteChat-Admin-Konsole Product Catalog, um Produkte, Collections und Bestand zu verwalten — oder eine CSV- oder Excel-Datei zu importieren — ohne das Geheimnis selbst verwalten zu müssen.

Wie funktioniert die Authentifizierung?

Von einem Server-Connector aus

Rufen Sie die API über HTTPS von einem vertrauenswürdigen Backend aus auf. Platzieren Sie einen JSON-String im Authorization-Header:

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

store_owner_api_secrete ist der öffentliche Feldname einschließlich der historischen Schreibweise. store_owner_api_secret wird ebenfalls akzeptiert. Dies ist kein Bearer-Token.

Aus dem SiteChat-Adminbereich

Die Seite Product Catalog sendet stattdessen Ihre angemeldete Admin-Sitzung:

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

access_token wird als Alias für admin_auth_token akzeptiert.

Der Query-Parameter store_key muss mit dem Header übereinstimmen. Bewahren Sie Inhaber-Geheimnisse nur in serverseitigen Umgebungsvariablen auf — niemals in einem Storefront-Skript, einer URL oder einem öffentlichen Repository.

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

Wie lade ich Produkte hoch?

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

Erforderliche Felder und Regeln

• Erforderliche Produktfelder: external_id, title, url, currency, price und available. status ist standardmäßig published.
• Optionaler Bestand: Setzen Sie tracks_inventory auf true und quantity auf dem Produkt oder der Variante auf einen nichtnegativen Wert. Shoply leitet dann die Verfügbarkeit aus dem Bestand ab (quantity > 0) und speichert total_inventory für Admin-Listen.
• source benennt die Katalogverbindung (nicht unbedingt eine Plattform). Verwenden Sie einen stabilen Namen wie woocommerce-main. Zulässige Zeichen: Kleinbuchstaben, Zahlen, Unterstriche und Bindestriche; bis zu 64 Zeichen. Im Adminbereich erstellte Produkte verwenden standardmäßig die Quelle admin.
• Die Produktidentität ist die Kombination aus Store, Quelle und externer ID. Batch- und einzelne POST-Upserts sind vollständige Ersetzungen, keine Patches: Ausgelassene optionale Felder werden geleert. Verwenden Sie PATCH für partielle Aktualisierungen.
• Batches enthalten 1–50 Produkte und maximal 2.000.000 Request-Bytes. Das validierte JSON jedes Produkts ist auf 128.000 Bytes begrenzt, mit höchstens 250 Varianten.
• Bevorzugen Sie dezimale Strings für Preise. Die Währung ist ein dreibuchstabiger Code in Großbuchstaben.
• Produkt- und Bild-URLs müssen HTTP(S) sein. Beim Import werden diese URLs nicht für Sie abgerufen.
• Verwenden Sie öffentliche metafields für durchsuchbare Produktspezifikationen (das SiteChat-Gegenstück zu den Shopify-Produktmetafeldern). Werte müssen einfache Strings sein. Das veraltete attributes wird als Alias ebenfalls akzeptiert. Privates Produkt-metadata wird nicht mehr unterstützt.
• draft- und archived-Produkte werden aus dem nächsten veröffentlichten Index ausgeschlossen. Ausverkaufte veröffentlichte Produkte bleiben mit angehängter Verfügbarkeit indexiert.
• Manuelle Collections speichern einen Titel, eine Beschreibung, einen Status und eine Liste von Produktzugehörigkeiten (source + external_id). Smarte/regelfbasierte Collections werden in dieser Version nicht unterstützt.

Beispiel für eine erfolgreiche Antwort

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

Shoply validiert die gesamte Anfrage, bevor Daten geschrieben werden. Ein HTTP-200 kann dennoch einige failed-Ergebnisse mit error: "storage_error" enthalten. Prüfen Sie jedes Ergebnis und wiederholen Sie fehlgeschlagene Produkte. Wenn index_status request_failed ist, war das Speichern erfolgreich, aber die Indexierung wurde nicht eingeplant — wiederholen Sie auch die bereits gespeicherten Produkte.

Python-Beispiel

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

Wie überprüfe ich ein importiertes Produkt?

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

Verwenden Sie denselben Authorization-Header. Die Antwort enthält schema_version, updated_at, index_status und das normalisierte product. Fehlende Datensätze liefern HTTP 404 zurück.

Nachdem der Hintergrund-Indexer einen Neuaufbau veröffentlicht hat, wird der Rücklesestatus pro Produkt zu indexed, excluded (für Entwurfs- oder archivierte Produkte) oder limit_exceeded. Verwenden Sie GET /merchant/products/list für Admin-Listen. Nutzen Sie Soft-Archive mit DELETE /merchant/products (oder setzen Sie status auf archived / draft), um ein Produkt aus dem nächsten veröffentlichten Index herauszuhalten; in dieser Version gibt es kein 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"])

Wie aktualisiere ich Varianten oder Metafelder sicher?

Für ein PATCH mit variants, metafields oder dem veralteten Feld attributes lesen Sie das Produkt zuerst mit GET. Erstellen Sie die Änderung auf Basis dieser Antwort und fügen Sie den zugehörigen updated_at-Wert der obersten Ebene als expected_updated_at in den PATCH-Body ein. Dies gilt auch beim Leeren von Varianten oder Metafeldern.

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 bedeutet, dass die Version fehlte oder eine andere Aktualisierung das Produkt geändert hat. Lesen Sie das neueste Produkt und führen Sie Ihre beabsichtigten Änderungen vor einem erneuten Versuch erneut zusammen. Hängen Sie keine neue Version an eine alte Variantenliste an: Dadurch könnten neuere Bestandswerte überschrieben werden.

Bestehende Integrationen, die diese Felder per PATCH ohne Version aktualisieren, müssen angepasst werden. PATCH-Anfragen nur mit skalaren Werten, dedizierte Bestandsanpassungen und vollständige Ersetzungen über POST oder Batch-Import benötigen dieses Feld nicht. Vollständige Ersetzungen ersetzen weiterhin das gesamte Produkt.

Kann ich Produktbilder hochladen?

Ja. Wenn ein Bild bereits unter einer dauerhaften öffentlichen HTTPS-URL verfügbar ist, fügen Sie diese URL in die Produktliste images oder in das Feld image einer Variante ein. Öffentliche S3-HTTPS-URLs funktionieren. Rohe s3://-Pfade und kurzlebige signierte URLs nicht.

Damit Shoply die Datei hostet, laden Sie rohe Bild-Bytes aus Ihrem Backend hoch:

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

Senden Sie die rohen Dateibytes, nicht JSON, Base64 oder Multipart-Formulardaten. JPEG, PNG und WebP werden akzeptiert, bis zu 10 MiB und 20 Millionen Pixel. Animierte Bilder werden nicht unterstützt. Shoply konvertiert das Bild in WebP und entfernt eingebettete Metadaten.

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 gibt url, content_type, size_bytes, width und height zurück. Das alleinige Hochladen eines Bildes verknüpft es nicht mit einem Produkt und fordert auch keine Indexierung an. Fügen Sie die zurückgegebene URL in ein vollständiges Produkt ein und senden Sie es erneut über /merchant/products/batch.

Wird dasselbe Bild für dasselbe Konto erneut hochgeladen, wird seine URL wiederverwendet. Ein geändertes Bild erhält eine neue URL. In dieser Version gibt es keinen Endpunkt zum Löschen von Bildern.

Wann erscheinen Produkte in Chat und Suche?

Nach einer erfolgreichen Batch-Speicherung fordert Shoply einen Neuaufbau des Hintergrundindexes an. Antworten melden index_status: "pending", bis der Worker den neuen Index veröffentlicht. Es gibt keine feste Garantie für die Abschlusszeit.

• Veröffentlichte Produkte gelangen sowohl in die Produktsuche als auch in das vom SiteChat-Chat verwendete Wissen.
• Entwürfe und archivierte Produkte werden beim nächsten Neuaufbau ausgeschlossen.
• Wenn die Indexierung nicht eingeplant wurde (index_status: "request_failed"), wiederholen Sie den Batch für die Produkte, die bereits erfolgreich gespeichert wurden.

Welche Fehler sollte ich erwarten?

Geheimnisse laufen nach 90 Tagen ab. Erstellen Sie vor dem Ablauf in Einstellungen → API-Geheimnis des Store-Inhabers einen Ersatz und widerrufen Sie jedes Geheimnis, das Sie nicht mehr benötigen. Dasselbe Geheimnis kann auch Analyse-, Konversations- und Wissens-Endpunkte aufrufen, die im Merchant-API-Leitfaden dokumentiert sind.

Wenn Sie Hilfe bei einer Integration benötigen, kontaktieren Sie Shoply AI.