So verwenden Sie die Shoply Merchant API

Mit der Shoply Merchant API kann ein Händler seine eigenen Shoply-Daten sicher in Reporting-Tools, Support-Workflows, geplanten Exporten und privaten Geschäftsanwendungen verwenden.

Jede Integration authentifiziert sich mit einem widerrufbaren, storespezifischen Zugangsschlüssel, der in den Shoply-Einstellungen erstellt wird. Sie müssen kein Shopify Admin API Access Token weitergeben, und eine Integration kann nur auf den Store zugreifen, der ihren Zugangsschlüssel ausgestellt hat.

Was kann ich mit der Merchant API tun?

Sie können die Merchant API verwenden, um:

• tägliche, wöchentliche oder monatliche Performance-Ergebnisse in eine Tabelle oder ein Data Warehouse zu exportieren.
• ein privates Dashboard für Sitzungen, Chats, Suchen, Produktklicks, Add-to-Cart-Ereignisse, Käufe und zugeordneten Umsatz zu erstellen.
• Kundenaktivitäten zu überwachen und ungewöhnliche Veränderungen beim Engagement zu erkennen.
• Chat- und Suchsitzungen für Support-, Merchandising- und Antwortqualitätsarbeit zu prüfen.
• den zeitlichen Verlauf einer einzelnen Unterhaltung abzurufen, wenn Sie ein Kundenproblem untersuchen.
• das von Shoply AI verwendete benutzerdefinierte Wissen zu erstellen, zu aktualisieren, aufzulisten und zu löschen.
• eine externe Webseite oder eine hochgeladene PDF-, Text- oder Markdown-Datei zur Wissensdatenbank hinzuzufügen.
• UTC-Ereignisdaten mit der lokalen Zeitzone des Stores abzugleichen.

Diese Anleitung dokumentiert sieben Endpunkte. Fünf davon sind dieselben Endpunkte, die von Shoply Admin → Analytics verwendet werden, während zwei die Wissensdatenbank verwalten:

Die folgenden Response-Bodys sind repräsentative Beispiele. Ihre Felder und Werte spiegeln die für Ihren Store erfasste Aktivität wider.

Bereitstellungsanforderung: Die Authentifizierung mit dem Secret des Store-Inhabers muss auf dem API-Server bereitgestellt sein, den Sie aufrufen. Wenn ein gültiges Secret HTTP 403 mit No access_token found zurückgibt, läuft auf diesem Server noch der ältere Authentifizierungscode, der nur Access Tokens unterstützt.

Wie erstelle ich ein API-Secret?

1. Öffnen Sie Ihren Shoply AI Admin.
2. Gehen Sie zu Settings → Store owner API secret.
3. Erstellen Sie ein Secret und geben Sie ihm einen Namen, der die Integration identifiziert, zum Beispiel Weekly reporting export.
4. Kopieren Sie das Secret, sobald es angezeigt wird. Shoply zeigt den Klartextwert nur einmal an.

Jedes Secret ist 90 Tage lang gültig. Ein Store kann für verschiedene Integrationen separate Secrets haben, und Sie können ein Secret widerrufen, ohne die anderen zu unterbrechen.

Speichern Sie diese Werte als serverseitige Umgebungsvariablen:

export SHOPLY_STORE_KEY="your-store.myshopify.com"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

Verwenden Sie für SHOPLY_STORE_KEY die permanente myshopify.com-Domain des Stores, auch wenn Käufer normalerweise eine benutzerdefinierte Domain besuchen.

Wie funktioniert die Authentifizierung?

Jede Merchant-API-Anfrage sendet einen Authorization-Header, dessen Wert ein JSON-String ist:

{
  "store_key": "your-store.myshopify.com",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete ist der exakte öffentliche Feldname, einschließlich seiner historischen Schreibweise. Dies ist kein Bearer-Token. Setzen Sie den vollständigen JSON-String direkt in den Authorization-Header.

Bewahren Sie das Secret nur im Backend-Code auf. Platzieren Sie es nicht in einer URL, einem Browser-Bundle, einem öffentlichen Repository, einem Analytics-Ereignis oder einem Anwendungsprotokoll.

Gibt es offizielle Python- und Node.js-Pakete?

Ja. Shoply veröffentlicht zwei serverseitige Pakete, die die erforderliche Authentifizierung automatisch hinzufügen und die Merchant API als typisierte Funktionen bereitstellen. Beide Pakete sind Open Source unter der GitHub-Organisation shoplyai-public.

Python-Paket

Das Paket shoply-merchant-api unterstützt Python 3.12 und verwendet Pydantic-v2-Response-Modelle. Installieren Sie die fest angeheftete Version 2.1.3:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/shoplyai-public/shoply-merchant-api.git@v2.1.3"

Rufen Sie die neuesten Chat- und Suchsitzungen als typisierte SessionSummary-Modelle ab:

import os
 
from shoply_merchant_api import ShoplyMerchantClient
 
 
with ShoplyMerchantClient(
    store_key=os.environ["SHOPLY_STORE_KEY"],
    api_secret=os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
) as shoply:
    session_response = shoply.list_sessions(limit=40)
 
for conversation in session_response.data:
    print(conversation.customer_id, conversation.user_questions)

Das Paket stellt außerdem Funktionen für Analytics, Aktivitätszahlen, vollständige Sitzungsverläufe, die Store-Zeitzone und Wissensverwaltung bereit. Siehe den Leitfaden für Business-Anwendungsfälle  und die API-Referenz .

Node.js- und TypeScript-Paket

Das Repository shoply-merchant-api-js stellt das Paket @shoplyai/merchant-api für Node.js 20 oder neuer bereit. Es ist ein ESM-Paket mit integrierten TypeScript-Deklarationen und ohne Laufzeitabhängigkeiten. Installieren Sie die fest angeheftete Version 2.1.3 direkt von GitHub:

npm install "github:shoplyai-public/shoply-merchant-api-js#v2.1.3"

Rufen Sie dieselben neuesten Sitzungen von einem Node.js-Server ab:

import { ShoplyMerchantClient } from "@shoplyai/merchant-api";
 
const storeKey = process.env.SHOPLY_STORE_KEY;
const apiSecret = process.env.SHOPLY_STORE_OWNER_API_SECRETE;
if (!storeKey || !apiSecret) {
  throw new Error("SHOPLY_STORE_KEY and SHOPLY_STORE_OWNER_API_SECRETE are required");
}
 
const shoply = new ShoplyMerchantClient({
  storeKey,
  apiSecret,
});
 
const sessionResponse = await shoply.listSessions({ limit: 40 });
 
for (const conversation of sessionResponse.data) {
  console.log(conversation.customer_id, conversation.user_questions);
}

Das npm-Paket deckt dieselben Merchant-API-Endpunkte ab wie das Python-Paket. Siehe den Leitfaden für Business-Anwendungsfälle  und die API-Referenz .

Beide Pakete sind für vertrauenswürdige Backend-Dienste, geplante Jobs und private interne Tools gedacht. Importieren Sie keines der beiden Pakete in Storefront-Code und legen Sie das API-Secret nicht in einem Browser-Bundle offen.

Kann ich die HTTP-API ohne Paket aufrufen?

Ja. Die Merchant API bleibt eine standardmäßige HTTPS-API. Die Low-Level-Python-Beispiele unten verwenden Requests, damit Sie den vollständigen Wire-Contract sehen oder aus einer anderen Sprache integrieren können.

Installieren Sie Requests, falls Ihre Umgebung es noch nicht enthält:

python -m pip install requests

Der folgende Helper fügt jeder Anfrage den Store-Key und den Authentifizierungs-Header hinzu:

import json
import os
from typing import Any
 
import requests
 
BASE_URL = "https://api.shoplyai.ai"
STORE_KEY = os.environ["SHOPLY_STORE_KEY"]
STORE_OWNER_API_SECRETE = os.environ["SHOPLY_STORE_OWNER_API_SECRETE"]
 
session = requests.Session()
session.headers.update({
    "Authorization": json.dumps({
        "store_key": STORE_KEY,
        "store_owner_api_secrete": STORE_OWNER_API_SECRETE,
    })
})
 
 
def shoply_get(api_name: str, **params: Any) -> dict[str, Any]:
    """Call one store-scoped Shoply API and surface HTTP or API-level errors."""
    response = session.get(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        timeout=30,
    )
    response.raise_for_status()
 
    payload = response.json()
    if payload.get("error") is not None or payload.get("statusCode") not in (None, 200):
        raise RuntimeError(payload.get("error", "Shoply API request failed"))
    return payload
 
 
def shoply_post(
    api_name: str,
    payload: dict[str, Any] | None = None,
    **params: Any,
) -> dict[str, Any]:
    """Write store-scoped data and surface HTTP or API-level errors."""
    response = session.post(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
 
    result = response.json()
    if result.get("error") is not None or result.get("statusCode") not in (None, 200):
        raise RuntimeError(result.get("error", "Shoply API request failed"))
    return result

Die folgenden Beispiele verwenden diesen gemeinsamen Client. Beide Helper fügen den authentifizierten Store-Key automatisch hinzu.

Kann ich Shoply-AI-Wissen über die API verwalten?

Ja. admin_store_knowledge verwendet GET, um Wissen abzurufen, und POST, um es zu erstellen, zu aktualisieren, zu löschen oder erneut crawlen zu lassen. Ein POST, das eine vorhandene Wissens-ID verwendet, aktualisiert diesen Eintrag; die Verwendung einer neuen ID erstellt einen Eintrag.

Bevor Sie Aktualisierungen automatisieren, planen Sie nützliches Store-Wissen mit den Beispielen in unserem Trainingsleitfaden.

Schreibvorgänge für Wissen können Antworten verändern, die Käufern angezeigt werden. Verwenden Sie ein dediziertes Secret für das System, das Wissen verwaltet, validieren Sie Inhalte vor dem Senden und legen Sie diesen schreibfähigen Zugangsschlüssel niemals im Storefront-JavaScript offen.

Vorhandenes Wissen auflisten

knowledge_payload = shoply_get(
    "admin_store_knowledge",
    knowledge_id_to_retrieve="_ALL_",
)
 
for knowledge_id, knowledge in knowledge_payload["data"].items():
    print(knowledge_id, knowledge.get("title"))

Beispielantwort

{
  "data": {
    "knowledge::shipping-policy": {
      "title": "Shipping policy",
      "text": "Orders leave our warehouse within two business days.",
      "epoch_edit": 1787211246
    }
  }
}

Benutzerdefiniertes Textwissen erstellen oder aktualisieren

Wählen Sie eine stabile, eindeutige Wissens-ID. Verwenden Sie beim Aktualisieren desselben Eintrags dieselbe ID erneut.

from time import time
 
knowledge_id = "knowledge::shipping-policy"
result = shoply_post(
    "admin_store_knowledge",
    {
        knowledge_id: {
            "title": "Shipping policy",
            "text": (
                "Orders leave our warehouse within two business days. "
                "Standard delivery normally takes three to five business days."
            ),
            "epoch_edit": int(time()),
        }
    },
)
 
print(result)

Beispielantwort

{
  "statusCode": 200
}

Eine erfolgreiche Antwort bedeutet, dass das Wissen gespeichert wurde. Die Suchindizierung kann einige Minuten dauern, daher erscheint eine neue Antwort möglicherweise nicht sofort. Wenn die API meldet, dass der Inhalt gespeichert wurde, die Indizierung aber verzögert ist, bestätigen Sie den gespeicherten Eintrag mit GET, bevor Sie den Schreibvorgang erneut versuchen.

Eine externe Webseite hinzufügen

Verwenden Sie eine ID, die mit external_url:: beginnt. Tragen Sie die vollständige http://- oder https://-URL in text ein.

from time import time
 
result = shoply_post(
    "admin_store_knowledge",
    {
        "external_url::returns-policy": {
            "title": "Returns and exchanges",
            "text": "https://www.example.com/policies/returns",
            "epoch_edit": int(time()),
        }
    },
)

Eine Wissensdatei hochladen und registrieren

Wissensdateien müssen PDF, TXT oder Markdown sein und kleiner als 5 MB. Laden Sie die Datei zuerst hoch und speichern Sie dann den zurückgegebenen privaten S3-Speicherort als Wissenseintrag.

from pathlib import Path
from time import time
 
file_path = Path("shipping-policy.md")
with file_path.open("rb") as file_handle:
    upload_response = session.post(
        f"{BASE_URL}/user_generated_file",
        params={"store_key": STORE_KEY, "folder": "knowledge_file"},
        files={"file": (file_path.name, file_handle, "text/markdown")},
        timeout=60,
    )
 
upload_response.raise_for_status()
uploaded = upload_response.json()
if uploaded.get("statusCode") != 200:
    raise RuntimeError(uploaded.get("error", "Knowledge file upload failed"))
 
shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_file::shipping-policy": {
            "title": "Shipping policy document",
            "text": uploaded["file_url"],
            "epoch_edit": int(time()),
        }
    },
)

Beispielantwort für Upload

{
  "message": "File uploaded successfully",
  "statusCode": 200,
  "file_url": "s3://shoplystores/your-store.myshopify.com/uploads/shipping-policy.md"
}

Behandeln Sie file_url als einen intransparenten privaten Speicherort, der von Shoply zurückgegeben wird. Konstruieren oder ändern Sie ihn nicht selbst.

Wissen löschen

Das Löschen ist endgültig. Rufen Sie zuerst die aktuellen Einträge ab und senden Sie nur die exakten IDs, die Sie entfernen möchten.

result = shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_ids_to_delete": [
            "knowledge::shipping-policy",
            "external_url::returns-policy",
            "knowledge_file::shipping-policy",
        ]
    },
)

Ein erneutes Crawlen der Website anfordern

Verwenden Sie ein erneutes Crawlen, nachdem sich der Inhalt auf der Website des Händlers geändert hat. Nach jeder Aktualisierung von benutzerdefiniertem Text ist dies normalerweise nicht erforderlich.

result = shoply_post(
    "admin_store_knowledge",
    re_crawl_ind="true",
)

Business-Anwendungsfälle

• Versand-, Rückgabe-, Garantie-, Größen- oder Produktpflegehinweise aus einem internen Content-System synchronisieren.
• Vorübergehende Kampagnen- oder Feiertagsinformationen veröffentlichen, ohne sie manuell in Shoply Admin zu kopieren.
• Eine Richtlinien-Webseite oder ein freigegebenes Dokument als Teil eines Deployment-Workflows zur Wissensdatenbank hinzufügen.
• Veraltete Hinweise entfernen, sobald eine Richtlinie oder Aktion endet.

Merchant-API-Beispiele

1. Performance-Analytics abrufen

admin_store_analytics versorgt die Tabelle Analytics → Summary. Es gibt Sitzungen, Chats, Suchen, Klicks, Add-to-Cart-Ereignisse, Käufe und zugeordneten Umsatz zurück.

Endpunkt

GET https://api.shoplyai.ai/admin_store_analytics

Query-Parameter

Monatsberichte verwenden die in Shoply gespeicherte monatliche Historie und benötigen keine Datumsgrenzen.

Python-Beispiel

daily_report = shoply_get(
    "admin_store_analytics",
    report_type="daily",
    start_date="20260801",
    end_date="20260820",
)
 
for row in daily_report["data"]:
    print(row["date"], row["sessions"], row["purchases"], row["revenue"])
 
print("Totals:", daily_report["totals"])
 
# Weekly rows use the Monday of each week as their date label.
weekly_report = shoply_get(
    "admin_store_analytics",
    report_type="weekly",
    start_date="20260701",
    end_date="20260820",
)
 
# Monthly requests do not need start_date or end_date.
monthly_report = shoply_get("admin_store_analytics", report_type="monthly")

Beispielantwort

{
  "data": [
    {
      "date": "20260820",
      "sessions": 42,
      "chats": 18,
      "searches": 24,
      "clicks": 11,
      "add_to_cart": 5,
      "purchases": 2,
      "revenue": "$168.00",
      "revenue_usd": "$168.00"
    }
  ],
  "totals": {
    "date": "totals",
    "sessions": 42,
    "chats": 18,
    "searches": 24,
    "clicks": 11,
    "add_to_cart": 5,
    "purchases": 2,
    "revenue": "$168.00",
    "revenue_usd": "$168.00"
  },
  "report_type": "daily"
}

Der Umsatz kann mehr als eine Währung enthalten. Behandeln Sie revenue als Anzeigetext. Verwenden Sie revenue_usd, wenn Sie den von Shoply angezeigten normalisierten USD-Wert benötigen.

Business-Anwendungsfälle

• Eine tägliche Zusammenfassung der Verkaufsauswirkungen an den Händler oder das E-Commerce-Team senden.
• Suchen, Produktklicks, Add-to-Cart-Ereignisse und Käufe vergleichen, um Abbrüche im Funnel zu finden.
• Ein wöchentliches oder monatliches Business-Intelligence-Dashboard speisen, ohne die Shoply-Admin-Seite zu scrapen.
• Den zugeordneten Umsatz im Zeitverlauf verfolgen und mit Merchandising- oder Kampagnenänderungen vergleichen.

2. Die Store-Zeitzone abrufen

admin_get_store_metadata liefert das Zeitzonen-Badge, das in Analytics → Chat & Search History angezeigt wird. Die Seite verwendet es, um UTC-Aktivität in die lokale Zeit des Stores zu übersetzen.

Endpunkt

GET https://api.shoplyai.ai/admin_get_store_metadata

Query-Parameter

Python-Beispiel

timezone_payload = shoply_get(
    "admin_get_store_metadata",
    metadata_key="time_zone",
)
 
timezone = timezone_payload["data"]
print(timezone["ianaTimezone"], timezone["timezoneOffsetMinutes"])

Beispielantwort

{
  "data": {
    "ianaTimezone": "America/Los_Angeles",
    "timezoneOffset": -7,
    "timezoneOffsetMinutes": -420
  },
  "statusCode": 200
}

Business-Anwendungsfälle

• UTC-Aktivität in dieselben lokalen Kalendertage gruppieren, die der Händler in Analytics sieht.
• Tägliche Exporte planen, nachdem der lokale Tag des Stores beendet ist.
• Berichte mit einer eindeutigen IANA-Zeitzone wie America/Los_Angeles beschriften.

Zeitzonen-Offsets können sich aufgrund von Sommerzeitregeln ändern. Bevorzugen Sie ianaTimezone, wenn Ihr Berichtssystem dies unterstützt, anstatt dauerhaft einen numerischen Offset zu speichern.

3. Aktivitätszahlen abrufen

query_api_usage_count gibt Store-Aktivität zurück, gruppiert nach UTC-Datum oder der ursprünglichen UTC-Minute. Es ist außerdem die Quelle für das Aktivitätsdiagramm in Analytics → Chat & Search History.

Endpunkt

GET https://api.shoplyai.ai/query_api_usage_count

Query-Parameter

Python-Beispiel

activity = shoply_get(
    "query_api_usage_count",
    start_dt_utc="2026-08-01 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    groupby="utc_date",
)
 
for row in activity["data"]:
    print(row)

Beispielantwort

{
  "data": [
    {
      "utc_date": "2026-08-20",
      "QA": 18,
      "CHAT": 18,
      "SEARCH": 20,
      "CACHED_SEARCH": 4,
      "PRODUCT_SEARCH": 22,
      "CLICK": 11,
      "ADD_TO_CART": 5,
      "CHECKOUT": 2
    }
  ]
}

Zeilen enthalten die für diesen Zeitraum verfügbaren Aktivitätszähler, wie Chat-Fragen, Suchen, Klicks, Add-to-Cart-Ereignisse und Checkout-Ereignisse. Zähler ohne Aktivität können fehlen, anstatt auf null gesetzt zu sein.

Business-Anwendungsfälle

• Ein stündliches oder tägliches Aktivitätsdiagramm wie das in Chat & Search History erstellen.
• Ungewöhnliche Traffic-Spitzen oder plötzliche Rückgänge beim Kundenengagement erkennen.
• Das Produktsuchvolumen mit Klicks, Add-to-Cart-Ereignissen und Checkouts vergleichen.
• Abschätzen, wann Support- und Merchandising-Teams die geschäftigsten Zeiträume überprüfen sollten.

4. Zusammenfassungen von Chat- und Suchsitzungen abrufen

query_sessionized_chat gibt einen kompakten Datensatz pro Kundensitzung zurück. Es versorgt außerdem die Sitzungsliste in Analytics → Chat & Search History.

Endpunkt

GET https://api.shoplyai.ai/query_sessionized_chat

Query-Parameter

Die neuesten 40 Sitzungen abrufen

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="undefined",
    end_dt_utc="undefined",
    num_sessions=40,
    ScanIndexForward="false",
)
 
sessions = summary_payload["data"]
for conversation in sessions:
    print(conversation["customer_id"], conversation.get("user_questions", ""))

Sitzungen in einem UTC-Bereich abrufen

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="2026-08-20 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    ScanIndexForward="false",
)

Wenn beide Zeitgrenzen vorhanden sind, gibt die API Sitzungen im vollständigen Bereich zurück; num_sessions begrenzt diese begrenzte Abfrage nicht.

Beispielantwort

{
  "data": [
    {
      "customer_id": "customer-or-session-id",
      "user_questions": "Do you have this in blue?\nWhen will it ship?",
      "start_timestamp_ms": 1787184000000,
      "end_timestamp_ms": 1787184065000,
      "session_types": "product information, click",
      "customer_email": null,
      "customer_info": {},
      "sentiment": "positive",
      "num_questions": 2,
      "num_searches": 1,
      "num_clicks": 1
    }
  ]
}

Optionale Felder variieren je nach Sitzung. Behalten Sie customer_id, start_timestamp_ms und end_timestamp_ms bei, wenn Sie den vollständigen Verlauf abrufen möchten.

Business-Anwendungsfälle

• Eine Stichprobe aktueller Unterhaltungen hinsichtlich Antwortqualität und Support-Schulung prüfen.
• Wiederholte Kundenfragen finden, die Produkttexte oder FAQs beeinflussen sollten.
• Sitzungen mit hoher Kaufabsicht identifizieren, die Suchen, Produktklicks oder andere Shopping-Aktionen enthalten.
• Eine Zeile pro Sitzung für Trendanalysen exportieren und dabei die größere Payload auf Ereignisebene vermeiden.

5. Eine vollständige Sitzung abrufen

Übergeben Sie eine ausgewählte Zusammenfassung an query_log_visualization, um die Kunden-, KI-, Such- und Commerce-Ereignisse abzurufen.

Endpunkt

GET https://api.shoplyai.ai/query_log_visualization

Query-Parameter

Python-Beispiel

from datetime import datetime, timezone
 
 
def utc_from_milliseconds(timestamp_ms: int) -> str:
    """Format a Shoply millisecond timestamp for the history API."""
    value = datetime.fromtimestamp(timestamp_ms / 1000, tz=timezone.utc)
    return value.strftime("%Y-%m-%d %H:%M:%S")
 
 
selected = sessions[0]
timeline_payload = shoply_get(
    "query_log_visualization",
    date_time_utc_start=utc_from_milliseconds(selected["start_timestamp_ms"]),
    date_time_utc_end=utc_from_milliseconds(selected["end_timestamp_ms"]),
    session_id=selected["customer_id"],
    start_timestamp_ms=selected["start_timestamp_ms"],
)
 
for event in timeline_payload["data"]:
    print(event.get("server_timestamp_ms"), event.get("action_type"))

Beispielantwort

{
  "data": [
    {
      "action_type": "QA",
      "session_id": "customer-or-session-id",
      "utc_date_time": "2026-08-20 00:00:00",
      "start_timestamp_ms": 1787184000000,
      "server_timestamp_ms": 1787184000123,
      "Q": {
        "question": "Do you have this in blue?",
        "question_context": {}
      },
      "task_id": "task-id",
      "list_tokens": [
        {
          "data_type": "LLMOutput",
          "data": "Yes. These blue options are currently available."
        }
      ],
      "dict_search_results": {}
    }
  ]
}

Der Verlauf kann Kundenfragen, KI-Antworten, Suchergebnisse, Produktklicks, Add-to-Cart-Ereignisse, Checkout-Ereignisse und die Beteiligung menschlicher Agenten enthalten. Verwenden Sie server_timestamp_ms, um gemischte Ereignistypen zu sortieren. Ältere Datensätze können weniger Felder enthalten.

Business-Anwendungsfälle

• Genau prüfen, was ein Kunde gefragt hat und was Shoply während einer Support-Untersuchung geantwortet hat.
• Die Antwortqualität zusammen mit den Suchergebnissen und Produkten überprüfen, die dem Käufer angezeigt wurden.
• Den Weg von der Frage bis zum Klick, Add-to-Cart oder Checkout rekonstruieren.
• Eine von einem Kunden gemeldete Sitzung diagnostizieren, ohne irrelevante Verlaufsdaten durchsuchen zu müssen.

Kann ich ein Secret für jede API verwenden?

Ja. Ein gültiges store_owner_api_secrete ist auf einen Store beschränkt und funktioniert für die oben genannten Merchant-API-Endpunkte. Für SiteChat-Konten authentifiziert dasselbe Secret auch die Katalog-Upload-APIs. Für sicherere Abläufe verwenden Sie separate benannte Secrets für verschiedene Systeme — zum Beispiel eines für einen nächtlichen Datenexport und ein anderes für ein internes Dashboard.

Wenn eine Integration stillgelegt wird oder kompromittiert ist, widerrufen Sie nur ihr Secret in den Shoply-Einstellungen. Die anderen Integrationen funktionieren weiterhin.

Was sollte ich über Ablauf, Datenschutz und Fehler wissen?

Lesen Sie außerdem Shoply-Datenquellen und Datenschutz, um zu verstehen, welche Informationen für Kundenantworten verfügbar sind.

• API-Secrets für Store-Inhaber laufen nach 90 Tagen ab. Erstellen Sie einen Ersatz und aktualisieren Sie die Integration vor dem Ablaufdatum.
• Die standardmäßige Aufbewahrungsfrist für Chat- und Suchverläufe von Shoply beträgt ebenfalls 90 Tage. Secret-Ablauf und Datenaufbewahrung sind getrennte Richtlinien.
• Verlaufsantworten können personenbezogene Daten enthalten, einschließlich Kundenkennungen, E-Mail-Adressen, ungefährem Standort, Fragen und Shopping-Aktivität. Speichern und verarbeiten Sie diese gemäß Ihrer Datenschutzrichtlinie und dem geltenden Recht.
• HTTP 403 bedeutet, dass das Secret fehlt, ungültig, abgelaufen, widerrufen oder einem anderen Store zugeordnet ist.
• HTTP 422 bedeutet normalerweise, dass ein erforderlicher Query-Parameter fehlt oder den falschen Namen hat.
• HTTP 500 oder eine Antwort mit statusCode: 500 bedeutet, dass die Anfrage Shoply erreicht hat, aber nicht abgeschlossen werden konnte. Wiederholen Sie temporäre Fehler mit Backoff und kontaktieren Sie uns, wenn der Fehler weiterhin auftritt.
• Verwenden Sie begrenzte UTC-Bereiche für Exporte und wiederkehrende Jobs, damit die Antworten handhabbar bleiben.

Ist die Produktsuche Teil der Merchant API?

Die öffentliche Produktsuch-API von Shoply hat eine andere Authentifizierung und einen anderen Anfragevertrag. Siehe So greifen Sie über die API auf Shoply AI Search zu, wenn Sie Produktsuchergebnisse für ein käuferorientiertes Erlebnis statt für private Händlerdaten möchten.

Können SiteChat-Händler einen Produktkatalog hochladen?

Ja. SiteChat-Konten können strukturierte Produkte und Produktbilder mit demselben API-Secret für Store-Inhaber hochladen. Diese Katalog-Endpunkte sind separat dokumentiert in So laden Sie Ihren Katalog für SiteChat hoch. Shopify-Stores synchronisieren Produkte weiterhin über Shopify und verwenden diese Upload-Routen nicht.

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