So laden Sie Ihren Katalog für SiteChat hoch

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

Diese Endpunkte verwenden dasselbe Settings → Store owner API secret wie der Rest der Shoply Merchant API, und die SiteChat-Adminseite Product Catalog kann sie mit Ihrem Admin-Zugriffstoken der angemeldeten Sitzung aufrufen. Shopify-Stores 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 manuelle Kollektionen 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 danach sowohl im Produktindex als auch im 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-Secret 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-Secret genauso wie bei anderen Merchant-API-Integrationen: So verwenden Sie die Shoply Merchant API. Öffnen Sie in der SiteChat-Admin-Konsole Product Catalog, um Produkte, Kollektionen und Lagerbestände zu verwalten — oder eine CSV- oder Excel-Datei zu importieren — ohne das Secret selbst verwalten zu müssen.

Wie funktioniert die Authentifizierung?

Von einem Server-Connector aus

Rufen Sie die API von einem vertrauenswürdigen Backend über HTTPS auf. Legen Sie einen JSON-String in den Header Authorization:

{
  "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-Secrets 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 Lagerbestand: Setzen Sie tracks_inventory auf true und quantity auf eine nicht negative Zahl beim Produkt oder bei der Variante. Shoply leitet dann die Verfügbarkeit aus dem Bestand ab (quantity > 0) und speichert total_inventory für Admin-Listen.
• source bezeichnet die Katalogverbindung (nicht zwingend eine Plattform). Verwenden Sie einen stabilen Namen wie woocommerce-main. Erlaubte 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 höchstens 2.000.000 Request-Bytes. Das validierte JSON jedes Produkts ist auf 128.000 Bytes begrenzt, mit höchstens 250 Varianten.
• Bevorzugen Sie Dezimal-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 (SiteChats Entsprechung zu Shopify-Produkt-Metafeldern). Werte müssen einfache Strings sein. Das ältere attributes wird als Alias akzeptiert. Private Produkt-metadata werden nicht mehr unterstützt.
• Produkte mit draft und archived werden aus dem nächsten veröffentlichten Index herausgelassen. Ausverkaufte veröffentlichte Produkte bleiben mit angehängter Verfügbarkeit indexiert.
• Manuelle Kollektionen speichern einen Titel, eine Beschreibung, einen Status und eine Liste von Produktzugehörigkeiten (source + external_id). Smarte/regelbasierten Kollektionen 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 vor dem Schreiben. 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 die Speicherung erfolgreich, aber die Indexierung wurde nicht eingeplant — senden Sie auch die gespeicherten Produkte erneut.

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 Header Authorization. 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 Status beim erneuten Auslesen pro Produkt zu indexed, excluded (für Entwurfs- oder archivierte Produkte) oder limit_exceeded. Verwenden Sie GET /merchant/products/list für Admin-Listen. Weich archivieren Sie 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"])

Kann ich Produktbilder hochladen?

Ja. Wenn ein Bild bereits unter einer dauerhaften öffentlichen HTTPS-URL verfügbar ist, setzen Sie diese URL in die Produktliste images oder in das Feld image einer Variante. Ö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-Form-Daten. 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 liefert url, content_type, size_bytes, width und height zurück. Das Hochladen eines Bildes allein 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.

Dasselbe Bild, das erneut für dasselbe Konto hochgeladen wird, verwendet dieselbe URL wieder. 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 Hintergrundindex 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 erscheinen sowohl in der Produktsuche als auch im Wissen, das vom SiteChat-Chat verwendet wird.
• Entwürfe und archivierte Produkte werden beim nächsten Neuaufbau ausgeschlossen.
• Wenn die Indexierung nicht eingeplant wurde (index_status: "request_failed"), senden Sie den Batch für die Produkte erneut, die bereits erfolgreich gespeichert wurden.

Mit welchen Fehlern sollte ich rechnen?

Secrets laufen nach 90 Tagen ab. Erstellen Sie vor dem Ablauf einen Ersatz unter Settings → Store owner API secret, und widerrufen Sie jedes Secret, das Sie nicht mehr benötigen. Dasselbe Secret kann auch Analytics-, Konversations- und Wissens-Endpunkte aufrufen, die im Merchant API guide dokumentiert sind.

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