Πώς να χρησιμοποιήσετε το Shoply Merchant API

Το Shoply Merchant API επιτρέπει σε έναν έμπορο να χρησιμοποιεί με ασφάλεια τα δικά του δεδομένα Shoply σε εργαλεία αναφορών, ροές εργασίας υποστήριξης, προγραμματισμένες εξαγωγές και ιδιωτικές επιχειρηματικές εφαρμογές.

Κάθε ενσωμάτωση αυθεντικοποιείται με ένα ανακλήσιμο διαπιστευτήριο περιορισμένο στο κατάστημα, το οποίο δημιουργείται στις Ρυθμίσεις του Shoply. Δεν χρειάζεται να κοινοποιήσετε ένα Shopify Admin API access token, και μια ενσωμάτωση μπορεί να αποκτήσει πρόσβαση μόνο στο κατάστημα που εξέδωσε το διαπιστευτήριό της.

Τι μπορώ να κάνω με το Merchant API;

Μπορείτε να χρησιμοποιήσετε το Merchant API για να:

• Εξάγετε ημερήσια, εβδομαδιαία ή μηνιαία αποτελέσματα απόδοσης σε υπολογιστικό φύλλο ή αποθήκη δεδομένων.
• Δημιουργήσετε έναν ιδιωτικό πίνακα ελέγχου για συνεδρίες, συνομιλίες, αναζητήσεις, κλικ προϊόντων, συμβάντα προσθήκης στο καλάθι, αγορές και αποδιδόμενα έσοδα.
• Παρακολουθείτε τη δραστηριότητα πελατών και να εντοπίζετε ασυνήθιστες αλλαγές στην αλληλεπίδραση.
• Ελέγχετε συνεδρίες συνομιλίας και αναζήτησης για υποστήριξη, εμπορική διαχείριση και εργασία πάνω στην ποιότητα απαντήσεων.
• Ανακτάτε το χρονολόγιο μιας μεμονωμένης συνομιλίας όταν διερευνάτε ένα ζήτημα πελάτη.
• Δημιουργείτε, ενημερώνετε, προβάλλετε και διαγράφετε την προσαρμοσμένη γνώση που χρησιμοποιείται από το Shoply AI.
• Προσθέτετε μια εξωτερική ιστοσελίδα ή ένα ανεβασμένο αρχείο PDF, κειμένου ή Markdown στη βάση γνώσης.
• Ευθυγραμμίζετε τα δεδομένα συμβάντων UTC με την τοπική ζώνη ώρας του καταστήματος.

Αυτός ο οδηγός τεκμηριώνει επτά endpoints. Τα πέντε είναι τα ίδια endpoints που χρησιμοποιούνται από το Shoply Admin → Analytics, ενώ τα δύο διαχειρίζονται τη βάση γνώσης:

Τα σώματα απαντήσεων παρακάτω είναι αντιπροσωπευτικά δείγματα. Τα δικά σας πεδία και τιμές θα αντικατοπτρίζουν τη δραστηριότητα που έχει καταγραφεί για το κατάστημά σας.

Απαίτηση ανάπτυξης: Η αυθεντικοποίηση με μυστικό ιδιοκτήτη καταστήματος πρέπει να είναι εγκατεστημένη στον διακομιστή API που καλείτε. Αν ένα έγκυρο μυστικό επιστρέφει HTTP 403 με No access_token found, αυτός ο διακομιστής εξακολουθεί να εκτελεί τον παλαιότερο κώδικα αυθεντικοποίησης μόνο με access token.

Πώς δημιουργώ ένα μυστικό API;

1. Ανοίξτε το Shoply AI admin σας.
2. Μεταβείτε στις Settings → Store owner API secret.
3. Δημιουργήστε ένα μυστικό και δώστε του ένα όνομα που να αναγνωρίζει την ενσωμάτωση, όπως Weekly reporting export.
4. Αντιγράψτε το μυστικό όταν εμφανιστεί. Το Shoply εμφανίζει την τιμή plaintext μόνο μία φορά.

Κάθε μυστικό είναι έγκυρο για 90 ημέρες. Ένα κατάστημα μπορεί να έχει ξεχωριστά μυστικά για ξεχωριστές ενσωματώσεις, και μπορείτε να ανακαλέσετε ένα μυστικό χωρίς να διακόψετε τα υπόλοιπα.

Αποθηκεύστε αυτές τις τιμές ως μεταβλητές περιβάλλοντος στην πλευρά του διακομιστή:

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

Χρησιμοποιήστε το μόνιμο domain myshopify.com του καταστήματος για το SHOPLY_STORE_KEY, ακόμη κι αν οι αγοραστές επισκέπτονται συνήθως ένα προσαρμοσμένο domain.

Πώς λειτουργεί η αυθεντικοποίηση;

Κάθε αίτημα Merchant API στέλνει ένα header Authorization του οποίου η τιμή είναι μια συμβολοσειρά JSON:

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

Το store_owner_api_secrete είναι το ακριβές δημόσιο όνομα πεδίου, συμπεριλαμβανομένης της ιστορικής ορθογραφίας του. Αυτό δεν είναι token Bearer. Τοποθετήστε ολόκληρη τη συμβολοσειρά JSON απευθείας στο header Authorization.

Κρατήστε το μυστικό μόνο σε backend κώδικα. Μην το τοποθετείτε σε URL, browser bundle, δημόσιο repository, συμβάν analytics ή log εφαρμογής.

Υπάρχουν επίσημα πακέτα για Python και Node.js;

Ναι. Το Shoply δημοσιεύει δύο πακέτα server-side που προσθέτουν αυτόματα την απαιτούμενη αυθεντικοποίηση και εκθέτουν το Merchant API ως typed functions. Και τα δύο πακέτα είναι open source στο GitHub organization shoplyai-public.

Πακέτο Python

Το πακέτο shoply-merchant-api υποστηρίζει Python 3.12 και χρησιμοποιεί response models του Pydantic v2. Εγκαταστήστε την pinned έκδοση 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"

Ανακτήστε τις πιο πρόσφατες συνεδρίες συνομιλίας και αναζήτησης ως typed models SessionSummary:

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)

Το πακέτο παρέχει επίσης functions για analytics, μετρήσεις δραστηριότητας, πλήρη χρονολόγια συνεδριών, ζώνη ώρας καταστήματος και διαχείριση γνώσης. Δείτε τον οδηγό επιχειρηματικών περιπτώσεων χρήσης  και το API reference .

Πακέτο Node.js και TypeScript

Το repository shoply-merchant-api-js παρέχει το πακέτο @shoplyai/merchant-api για Node.js 20 ή νεότερο. Είναι πακέτο ESM με ενσωματωμένες δηλώσεις TypeScript και χωρίς runtime dependencies. Εγκαταστήστε την pinned έκδοση 2.1.3 απευθείας από το GitHub:

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

Ανακτήστε τις ίδιες πιο πρόσφατες συνεδρίες από έναν διακομιστή Node.js:

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);
}

Το npm package καλύπτει τα ίδια Merchant API endpoints με το πακέτο Python. Δείτε τον οδηγό επιχειρηματικών περιπτώσεων χρήσης  και το API reference .

Και τα δύο πακέτα προορίζονται για αξιόπιστες backend υπηρεσίες, προγραμματισμένες εργασίες και ιδιωτικά εσωτερικά εργαλεία. Μην εισάγετε κανένα από τα δύο πακέτα σε storefront κώδικα και μην εκθέτετε το μυστικό API σε browser bundle.

Μπορώ να καλέσω το HTTP API χωρίς πακέτο;

Ναι. Το Merchant API παραμένει ένα τυπικό HTTPS API. Τα παρακάτω παραδείγματα χαμηλού επιπέδου σε Python χρησιμοποιούν Requests ώστε να μπορείτε να δείτε ολόκληρο το wire contract ή να ενσωματωθείτε από άλλη γλώσσα.

Εγκαταστήστε το Requests αν το περιβάλλον σας δεν το περιλαμβάνει ήδη:

python -m pip install requests

Ο παρακάτω helper προσθέτει το store key και το authentication header σε κάθε αίτημα:

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

Τα παρακάτω παραδείγματα χρησιμοποιούν αυτόν τον κοινό client. Και οι δύο helpers προσθέτουν αυτόματα το αυθεντικοποιημένο store key.

Μπορώ να διαχειρίζομαι τη γνώση του Shoply AI μέσω του API;

Ναι. Το admin_store_knowledge χρησιμοποιεί GET για την ανάκτηση γνώσης και POST για τη δημιουργία, ενημέρωση, διαγραφή ή επανασάρωσή της. Ένα POST που χρησιμοποιεί υπάρχον knowledge ID ενημερώνει αυτή την καταχώριση· η χρήση νέου ID δημιουργεί μία νέα.

Πριν αυτοματοποιήσετε ενημερώσεις, σχεδιάστε χρήσιμη γνώση καταστήματος με τα παραδείγματα του οδηγού εκπαίδευσής μας.

Οι εγγραφές γνώσης μπορούν να αλλάξουν τις απαντήσεις που εμφανίζονται στους αγοραστές. Χρησιμοποιήστε ένα αποκλειστικό μυστικό για το σύστημα που διαχειρίζεται τη γνώση, επικυρώστε το περιεχόμενο πριν το στείλετε και μην εκθέτετε ποτέ αυτό το διαπιστευτήριο με δυνατότητα εγγραφής σε storefront JavaScript.

Λίστα υπάρχουσας γνώσης

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

Δείγμα απάντησης

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

Δημιουργία ή ενημέρωση προσαρμοσμένης γνώσης κειμένου

Επιλέξτε ένα σταθερό, μοναδικό knowledge ID. Χρησιμοποιήστε ξανά το ίδιο ID όταν ενημερώνετε αυτή την καταχώριση.

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)

Δείγμα απάντησης

{
  "statusCode": 200
}

Μια επιτυχής απάντηση σημαίνει ότι η γνώση αποθηκεύτηκε. Η ευρετηρίαση αναζήτησης μπορεί να χρειαστεί λίγα λεπτά, οπότε μια νέα απάντηση μπορεί να μην εμφανιστεί αμέσως. Αν το API αναφέρει ότι το περιεχόμενο αποθηκεύτηκε αλλά η ευρετηρίαση καθυστερεί, επιβεβαιώστε την αποθηκευμένη καταχώριση με GET πριν επαναλάβετε την εγγραφή.

Προσθήκη εξωτερικής ιστοσελίδας

Χρησιμοποιήστε ένα ID που αρχίζει με external_url::. Τοποθετήστε το πλήρες URL http:// ή https:// στο text.

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()),
        }
    },
)

Μεταφόρτωση και καταχώριση αρχείου γνώσης

Τα αρχεία γνώσης πρέπει να είναι PDF, TXT ή Markdown και μικρότερα από 5 MB. Ανεβάστε πρώτα το αρχείο και στη συνέχεια αποθηκεύστε την ιδιωτική τοποθεσία S3 που επιστρέφεται ως καταχώριση γνώσης.

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()),
        }
    },
)

Δείγμα απάντησης μεταφόρτωσης

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

Αντιμετωπίστε το file_url ως αδιαφανή ιδιωτική τοποθεσία που επιστρέφεται από το Shoply. Μην το κατασκευάζετε ή το τροποποιείτε μόνοι σας.

Διαγραφή γνώσης

Η διαγραφή είναι μόνιμη. Ανακτήστε πρώτα τις τρέχουσες καταχωρίσεις και στείλτε μόνο τα ακριβή ID που σκοπεύετε να αφαιρέσετε.

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

Αίτημα για επανασάρωση ιστοσελίδας

Χρησιμοποιήστε επανασάρωση αφού αλλάξει το περιεχόμενο στην ιστοσελίδα του εμπόρου. Κανονικά δεν είναι απαραίτητη μετά από κάθε ενημέρωση προσαρμοσμένου κειμένου.

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

Επιχειρηματικές περιπτώσεις χρήσης

• Συγχρονίστε οδηγίες αποστολής, επιστροφών, εγγύησης, μεγεθών ή φροντίδας προϊόντων από ένα εσωτερικό σύστημα περιεχομένου.
• Δημοσιεύστε προσωρινές πληροφορίες καμπάνιας ή εορτών χωρίς να τις αντιγράφετε χειροκίνητα στο Shoply Admin.
• Προσθέστε μια ιστοσελίδα πολιτικής ή ένα εγκεκριμένο έγγραφο στη βάση γνώσης ως μέρος μιας ροής ανάπτυξης.
• Αφαιρέστε παρωχημένες οδηγίες μόλις λήξει μια πολιτική ή προωθητική ενέργεια.

Παραδείγματα Merchant API

1. Ανάκτηση analytics απόδοσης

Το admin_store_analytics τροφοδοτεί τον πίνακα Analytics → Summary. Επιστρέφει συνεδρίες, συνομιλίες, αναζητήσεις, κλικ, συμβάντα προσθήκης στο καλάθι, αγορές και αποδιδόμενα έσοδα.

Endpoint

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

Query Parameters

Οι μηνιαίες αναφορές χρησιμοποιούν το αποθηκευμένο μηνιαίο ιστορικό του Shoply και δεν απαιτούν όρια ημερομηνιών.

Παράδειγμα Python

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

Δείγμα απάντησης

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

Τα έσοδα μπορεί να περιέχουν περισσότερα από ένα νομίσματα. Αντιμετωπίστε το revenue ως κείμενο εμφάνισης. Χρησιμοποιήστε το revenue_usd όταν χρειάζεστε την κανονικοποιημένη τιμή σε USD που εμφανίζει το Shoply.

Επιχειρηματικές περιπτώσεις χρήσης

• Στείλτε μια ημερήσια σύνοψη επίδρασης στις πωλήσεις στον έμπορο ή στην ομάδα ecommerce.
• Συγκρίνετε αναζητήσεις, κλικ προϊόντων, συμβάντα προσθήκης στο καλάθι και αγορές για να βρείτε απώλειες στο funnel.
• Τροφοδοτήστε έναν εβδομαδιαίο ή μηνιαίο πίνακα business-intelligence χωρίς scraping της σελίδας Shoply Admin.
• Παρακολουθήστε τα αποδιδόμενα έσοδα με την πάροδο του χρόνου και συγκρίνετέ τα με αλλαγές σε merchandising ή καμπάνιες.

2. Ανάκτηση της ζώνης ώρας του καταστήματος

Το admin_get_store_metadata παρέχει το badge ζώνης ώρας που εμφανίζεται στο Analytics → Chat & Search History. Η σελίδα το χρησιμοποιεί για να μεταφράζει τη δραστηριότητα UTC στην τοπική ώρα του καταστήματος.

Endpoint

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

Query Parameters

Παράδειγμα Python

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

Δείγμα απάντησης

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

Επιχειρηματικές περιπτώσεις χρήσης

• Ομαδοποιήστε τη δραστηριότητα UTC στις ίδιες τοπικές ημερολογιακές ημέρες που βλέπει ο έμπορος στα Analytics.
• Προγραμματίστε ημερήσιες εξαγωγές αφού έχει τελειώσει η τοπική ημέρα του καταστήματος.
• Επισημάνετε αναφορές με μια σαφή ζώνη ώρας IANA όπως America/Los_Angeles.

Οι μετατοπίσεις ζώνης ώρας μπορεί να αλλάξουν λόγω κανόνων θερινής ώρας. Προτιμήστε το ianaTimezone όταν το σύστημα αναφορών σας το υποστηρίζει, αντί να αποθηκεύετε μόνιμα μία αριθμητική μετατόπιση.

3. Ανάκτηση μετρήσεων δραστηριότητας

Το query_api_usage_count επιστρέφει δραστηριότητα καταστήματος ομαδοποιημένη ανά ημερομηνία UTC ή ανά αρχικό λεπτό UTC. Είναι επίσης η πηγή για το γράφημα δραστηριότητας στο Analytics → Chat & Search History.

Endpoint

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

Query Parameters

Παράδειγμα Python

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)

Δείγμα απάντησης

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

Οι γραμμές περιλαμβάνουν τους μετρητές δραστηριότητας που είναι διαθέσιμοι για εκείνη την περίοδο, όπως ερωτήσεις συνομιλίας, αναζητήσεις, κλικ, συμβάντα προσθήκης στο καλάθι και συμβάντα checkout. Μετρητές χωρίς δραστηριότητα μπορεί να απουσιάζουν αντί να ορίζονται σε μηδέν.

Επιχειρηματικές περιπτώσεις χρήσης

• Δημιουργήστε ένα ωριαίο ή ημερήσιο γράφημα δραστηριότητας όπως αυτό στο Chat & Search History.
• Εντοπίστε ασυνήθιστες αιχμές επισκεψιμότητας ή ξαφνικές πτώσεις στην αλληλεπίδραση πελατών.
• Συγκρίνετε τον όγκο αναζήτησης προϊόντων με κλικ, συμβάντα προσθήκης στο καλάθι και checkout.
• Εκτιμήστε πότε οι ομάδες υποστήριξης και merchandising πρέπει να εξετάζουν τις περιόδους με τη μεγαλύτερη κίνηση.

4. Ανάκτηση περιλήψεων συνεδριών συνομιλίας και αναζήτησης

Το query_sessionized_chat επιστρέφει μία συμπαγή εγγραφή ανά συνεδρία πελάτη. Τροφοδοτεί επίσης τη λίστα συνεδριών στο Analytics → Chat & Search History.

Endpoint

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

Query Parameters

Ανάκτηση των τελευταίων 40 συνεδριών

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

Ανάκτηση συνεδριών σε εύρος UTC

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

Όταν υπάρχουν και τα δύο χρονικά όρια, το API επιστρέφει συνεδρίες σε όλο το πλήρες εύρος· το num_sessions δεν περιορίζει αυτό το οριοθετημένο query.

Δείγμα απάντησης

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

Τα προαιρετικά πεδία διαφέρουν ανά συνεδρία. Διατηρήστε τα customer_id, start_timestamp_ms και end_timestamp_ms αν σκοπεύετε να ανακτήσετε το πλήρες χρονολόγιο.

Επιχειρηματικές περιπτώσεις χρήσης

• Ελέγξτε ένα δείγμα πρόσφατων συνομιλιών για ποιότητα απαντήσεων και εκπαίδευση υποστήριξης.
• Βρείτε επαναλαμβανόμενες ερωτήσεις πελατών που θα πρέπει να επηρεάσουν το product copy ή τα FAQs.
• Εντοπίστε συνεδρίες υψηλής πρόθεσης που περιέχουν αναζητήσεις, κλικ προϊόντων ή άλλες ενέργειες αγορών.
• Εξάγετε μία γραμμή ανά συνεδρία για ανάλυση τάσεων, αποφεύγοντας το μεγαλύτερο payload σε επίπεδο συμβάντος.

5. Ανάκτηση μίας πλήρους συνεδρίας

Περάστε μια επιλεγμένη περίληψη στο query_log_visualization για να ανακτήσετε τα συμβάντα πελάτη, AI, αναζήτησης και εμπορίου της.

Endpoint

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

Query Parameters

Παράδειγμα Python

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

Δείγμα απάντησης

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

Το χρονολόγιο μπορεί να περιέχει ερωτήσεις πελατών, απαντήσεις AI, αποτελέσματα αναζήτησης, κλικ προϊόντων, συμβάντα προσθήκης στο καλάθι, συμβάντα checkout και συμμετοχή ανθρώπινου agent. Χρησιμοποιήστε το server_timestamp_ms για να ταξινομήσετε μικτούς τύπους συμβάντων. Οι παλαιότερες εγγραφές μπορεί να περιέχουν λιγότερα πεδία.

Επιχειρηματικές περιπτώσεις χρήσης

• Ελέγξτε ακριβώς τι ρώτησε ένας πελάτης και τι απάντησε το Shoply κατά τη διάρκεια μιας διερεύνησης υποστήριξης.
• Εξετάστε την ποιότητα απαντήσεων μαζί με τα αποτελέσματα αναζήτησης και τα προϊόντα που εμφανίστηκαν στον αγοραστή.
• Ανασυνθέστε τη διαδρομή από την ερώτηση στο κλικ, στην προσθήκη στο καλάθι ή στο checkout.
• Διαγνώστε μία συνεδρία που αναφέρθηκε από πελάτη χωρίς να αναζητάτε μέσα σε άσχετο ιστορικό.

Μπορώ να χρησιμοποιώ ένα μυστικό για κάθε API;

Ναι. Ένα έγκυρο store_owner_api_secrete περιορίζεται σε ένα κατάστημα και λειτουργεί σε όλα τα Merchant API endpoints παραπάνω. Για λογαριασμούς SiteChat, το ίδιο μυστικό αυθεντικοποιεί επίσης τα catalog upload APIs. Για ασφαλέστερες λειτουργίες, χρησιμοποιήστε ξεχωριστά ονομασμένα μυστικά για ξεχωριστά συστήματα—για παράδειγμα, ένα για νυχτερινή εξαγωγή δεδομένων και άλλο για έναν εσωτερικό πίνακα ελέγχου.

Αν μία ενσωμάτωση αποσυρθεί ή παραβιαστεί, ανακαλέστε μόνο το δικό της μυστικό στις Ρυθμίσεις του Shoply. Οι άλλες ενσωματώσεις θα συνεχίσουν να λειτουργούν.

Τι πρέπει να γνωρίζω για λήξη, απόρρητο και σφάλματα;

Δείτε επίσης τις πηγές δεδομένων και το απόρρητο του Shoply για να κατανοήσετε ποιες πληροφορίες είναι διαθέσιμες στις απαντήσεις προς πελάτες.

• Τα μυστικά API ιδιοκτήτη καταστήματος λήγουν μετά από 90 ημέρες. Δημιουργήστε αντικατάσταση και ενημερώστε την ενσωμάτωση πριν από την ημερομηνία λήξης της.
• Η τυπική περίοδος διατήρησης ιστορικού συνομιλιών και αναζήτησης του Shoply είναι επίσης 90 ημέρες. Η λήξη μυστικών και η διατήρηση δεδομένων είναι ξεχωριστές πολιτικές.
• Οι απαντήσεις ιστορικού μπορεί να περιέχουν προσωπικά δεδομένα, συμπεριλαμβανομένων αναγνωριστικών πελατών, διευθύνσεων email, κατά προσέγγιση τοποθεσίας, ερωτήσεων και αγοραστικής δραστηριότητας. Αποθηκεύστε και επεξεργαστείτε τα σύμφωνα με την πολιτική απορρήτου σας και την ισχύουσα νομοθεσία.
• Το HTTP 403 σημαίνει ότι το μυστικό λείπει, είναι μη έγκυρο, έχει λήξει, έχει ανακληθεί ή ανήκει σε διαφορετικό κατάστημα.
• Το HTTP 422 συνήθως σημαίνει ότι λείπει μια απαιτούμενη παράμετρος query ή ότι έχει λάθος όνομα.
• Το HTTP 500 ή μια απάντηση με statusCode: 500 σημαίνει ότι το αίτημα έφτασε στο Shoply αλλά δεν μπόρεσε να ολοκληρωθεί. Επαναλάβετε προσωρινές αποτυχίες με backoff και επικοινωνήστε μαζί μας αν το σφάλμα συνεχίζεται.
• Χρησιμοποιείτε οριοθετημένα εύρη UTC για εξαγωγές και επαναλαμβανόμενες εργασίες ώστε οι απαντήσεις να παραμένουν διαχειρίσιμες.

Είναι η αναζήτηση προϊόντων μέρος του Merchant API;

Το δημόσιο product-search API του Shoply έχει διαφορετικό συμβόλαιο αυθεντικοποίησης και αιτήματος. Δείτε το How to Access Shoply AI Search Through the API αν θέλετε αποτελέσματα αναζήτησης προϊόντων για εμπειρία προσανατολισμένη στον αγοραστή αντί για ιδιωτικά δεδομένα εμπόρου.

Μπορούν οι έμποροι SiteChat να ανεβάσουν κατάλογο προϊόντων;

Ναι. Οι λογαριασμοί SiteChat μπορούν να ανεβάσουν δομημένα προϊόντα και εικόνες προϊόντων με το ίδιο μυστικό API ιδιοκτήτη καταστήματος. Αυτά τα endpoints καταλόγου τεκμηριώνονται ξεχωριστά στο How to Upload Your Catalog for SiteChat. Τα καταστήματα Shopify συνεχίζουν να συγχρονίζουν προϊόντα μέσω Shopify και δεν χρησιμοποιούν αυτές τις διαδρομές μεταφόρτωσης.

Για βοήθεια με μια ενσωμάτωση, επικοινωνήστε με το Shoply AI.