Cách sử dụng Shoply Merchant API

Shoply Merchant API cho phép người bán sử dụng an toàn dữ liệu Shoply của chính họ trong các công cụ báo cáo, quy trình hỗ trợ, tác vụ xuất dữ liệu theo lịch và các ứng dụng doanh nghiệp riêng tư.

Mỗi tích hợp xác thực bằng một thông tin xác thực có thể thu hồi, được giới hạn theo từng cửa hàng và được tạo trong phần Cài đặt của Shoply. Bạn không cần chia sẻ Shopify Admin API access token, và một tích hợp chỉ có thể truy cập cửa hàng đã cấp thông tin xác thực đó.

Tôi có thể làm gì với Merchant API?

Bạn có thể dùng Merchant API để:

• Xuất kết quả hiệu suất hằng ngày, hằng tuần hoặc hằng tháng sang bảng tính hoặc kho dữ liệu.
• Xây dựng dashboard riêng cho phiên, cuộc trò chuyện, lượt tìm kiếm, lượt nhấp sản phẩm, sự kiện thêm vào giỏ, lượt mua và doanh thu được ghi nhận.
• Theo dõi hoạt động khách hàng và phát hiện các thay đổi bất thường trong mức độ tương tác.
• Xem lại các phiên chat và tìm kiếm để phục vụ hỗ trợ, tối ưu trưng bày sản phẩm và cải thiện chất lượng câu trả lời.
• Truy xuất dòng thời gian hội thoại của từng cuộc trò chuyện riêng lẻ khi điều tra một vấn đề của khách hàng.
• Tạo, cập nhật, liệt kê và xóa kiến thức tùy chỉnh được Shoply AI sử dụng.
• Thêm một trang web bên ngoài hoặc một tệp PDF, văn bản hoặc Markdown được tải lên vào kho kiến thức.
• Căn chỉnh dữ liệu sự kiện UTC với múi giờ địa phương của cửa hàng.

Hướng dẫn này mô tả bảy endpoint. Năm endpoint giống với các endpoint được dùng bởi Shoply Admin → Analytics, còn hai endpoint dùng để quản lý kho kiến thức:

Các phần thân phản hồi bên dưới là các mẫu đại diện. Trường và giá trị thực tế của bạn sẽ phản ánh hoạt động được ghi nhận cho cửa hàng của bạn.

Yêu cầu triển khai: Xác thực bằng secret của chủ cửa hàng phải được triển khai trên máy chủ API mà bạn gọi đến. Nếu một secret hợp lệ trả về HTTP 403 với No access_token found, máy chủ đó vẫn đang chạy mã xác thực cũ chỉ hỗ trợ access token.

Tôi tạo API Secret như thế nào?

1. Mở trang quản trị Shoply AI của bạn.
2. Đi đến Settings → Store owner API secret.
3. Tạo một secret và đặt tên giúp nhận diện tích hợp, chẳng hạn như Weekly reporting export.
4. Sao chép secret khi nó xuất hiện. Shoply chỉ hiển thị giá trị dạng plaintext một lần duy nhất.

Mỗi secret có hiệu lực trong 90 ngày. Một cửa hàng có thể có các secret riêng cho các tích hợp khác nhau, và bạn có thể thu hồi một secret mà không làm gián đoạn các secret còn lại.

Lưu các giá trị này dưới dạng biến môi trường phía máy chủ:

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

Sử dụng domain myshopify.com cố định của cửa hàng cho SHOPLY_STORE_KEY, ngay cả khi người mua thường truy cập qua một domain tùy chỉnh.

Cơ chế xác thực hoạt động như thế nào?

Mỗi yêu cầu Merchant API gửi một header Authorization có giá trị là một chuỗi JSON:

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

store_owner_api_secrete là tên trường công khai chính xác, bao gồm cả cách đánh vần lịch sử của nó. Đây không phải là Bearer token. Hãy đặt trực tiếp toàn bộ chuỗi JSON vào header Authorization.

Chỉ giữ secret trong mã backend. Không đặt nó trong URL, bundle trình duyệt, kho mã công khai, sự kiện analytics hoặc log ứng dụng.

Có package Python và Node.js chính thức không?

Có. Shoply phát hành hai package phía máy chủ tự động thêm xác thực bắt buộc và cung cấp Merchant API dưới dạng các hàm có kiểu dữ liệu. Cả hai package đều là mã nguồn mở trong tổ chức GitHub shoplyai-public.

Package Python

Package shoply-merchant-api hỗ trợ Python 3.12 và sử dụng các response model của Pydantic v2. Cài đặt bản phát hành 2.1.3 được cố định:

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"

Truy xuất các phiên chat và tìm kiếm mới nhất dưới dạng model SessionSummary có kiểu dữ liệu:

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)

Package này cũng cung cấp các hàm cho analytics, số lượng hoạt động, dòng thời gian phiên đầy đủ, múi giờ cửa hàng và quản lý kiến thức. Xem hướng dẫn tình huống sử dụng doanh nghiệp  và tài liệu tham chiếu API .

Package Node.js và TypeScript

Kho shoply-merchant-api-js cung cấp package @shoplyai/merchant-api cho Node.js 20 trở lên. Đây là package ESM với khai báo TypeScript tích hợp sẵn và không có dependency lúc runtime. Cài đặt bản phát hành 2.1.3 được cố định trực tiếp từ GitHub:

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

Truy xuất cùng các phiên mới nhất đó từ một máy chủ 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);
}

Package npm này bao phủ cùng các endpoint Merchant API như package Python. Xem hướng dẫn tình huống sử dụng doanh nghiệp  và tài liệu tham chiếu API .

Cả hai package đều dành cho các dịch vụ backend đáng tin cậy, tác vụ theo lịch và công cụ nội bộ riêng tư. Không import bất kỳ package nào vào mã storefront hoặc để lộ API secret trong bundle trình duyệt.

Tôi có thể gọi HTTP API mà không cần package không?

Có. Merchant API vẫn là một HTTPS API tiêu chuẩn. Các ví dụ Python mức thấp bên dưới sử dụng Requests để bạn có thể thấy toàn bộ wire contract hoặc tích hợp từ một ngôn ngữ khác.

Cài đặt Requests nếu môi trường của bạn chưa có sẵn:

python -m pip install requests

Hàm hỗ trợ bên dưới thêm store key và header xác thực vào mọi yêu cầu:

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

Các ví dụ bên dưới sử dụng client dùng chung này. Cả hai hàm hỗ trợ đều tự động thêm store key đã được xác thực.

Tôi có thể quản lý kiến thức của Shoply AI thông qua API không?

Có. admin_store_knowledge dùng GET để truy xuất kiến thức và POST để tạo, cập nhật, xóa hoặc thu thập lại dữ liệu. Một POST dùng knowledge ID đã tồn tại sẽ cập nhật mục đó; dùng một ID mới sẽ tạo mục mới.

Trước khi tự động hóa việc cập nhật, hãy lên kế hoạch cho kiến thức cửa hàng hữu ích với các ví dụ trong hướng dẫn huấn luyện của chúng tôi.

Các thao tác ghi kiến thức có thể thay đổi câu trả lời hiển thị cho người mua. Hãy dùng một secret riêng cho hệ thống quản lý kiến thức, xác thực nội dung trước khi gửi và tuyệt đối không để lộ thông tin xác thực có quyền ghi này trong JavaScript storefront.

Liệt kê kiến thức hiện có

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

Phản hồi mẫu

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

Tạo hoặc cập nhật kiến thức văn bản tùy chỉnh

Chọn một knowledge ID ổn định và duy nhất. Dùng lại cùng ID đó khi cập nhật mục này.

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)

Phản hồi mẫu

{
  "statusCode": 200
}

Phản hồi thành công có nghĩa là kiến thức đã được lưu. Việc lập chỉ mục tìm kiếm có thể mất vài phút, vì vậy câu trả lời mới có thể chưa xuất hiện ngay. Nếu API báo nội dung đã được lưu nhưng quá trình lập chỉ mục bị chậm, hãy xác nhận mục đã lưu bằng GET trước khi thử ghi lại.

Thêm một trang web bên ngoài

Dùng một ID bắt đầu bằng external_url::. Đặt URL đầy đủ http:// hoặc https:// vào 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()),
        }
    },
)

Tải lên và đăng ký một tệp kiến thức

Tệp kiến thức phải là PDF, TXT hoặc Markdown và nhỏ hơn 5 MB. Trước tiên hãy tải tệp lên, sau đó lưu vị trí S3 riêng tư được trả về như một mục kiến thức.

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

Phản hồi tải lên mẫu

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

Hãy coi file_url là một vị trí riêng tư không trong suốt được Shoply trả về. Đừng tự tạo hoặc tự thay đổi nó.

Xóa kiến thức

Việc xóa là vĩnh viễn. Hãy truy xuất các mục hiện tại trước, và chỉ gửi đúng các ID mà bạn muốn xóa.

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

Yêu cầu thu thập lại website

Sử dụng recrawl sau khi nội dung trên website của người bán thay đổi. Thông thường không cần thiết sau mỗi lần cập nhật văn bản tùy chỉnh.

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

Tình huống sử dụng doanh nghiệp

• Đồng bộ hướng dẫn về vận chuyển, đổi trả, bảo hành, kích cỡ hoặc chăm sóc sản phẩm từ một hệ thống nội dung nội bộ.
• Xuất bản thông tin chiến dịch tạm thời hoặc dịp lễ mà không cần sao chép thủ công vào Shoply Admin.
• Thêm một trang chính sách hoặc tài liệu đã được phê duyệt vào kho kiến thức như một phần của quy trình triển khai.
• Xóa hướng dẫn lỗi thời ngay khi một chính sách hoặc chương trình khuyến mãi kết thúc.

Ví dụ Merchant API

1. Truy xuất phân tích hiệu suất

admin_store_analytics cung cấp dữ liệu cho bảng Analytics → Summary. Nó trả về số phiên, cuộc trò chuyện, lượt tìm kiếm, lượt nhấp, sự kiện thêm vào giỏ, lượt mua và doanh thu được ghi nhận.

Endpoint

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

Query Parameters

Báo cáo theo tháng sử dụng lịch sử theo tháng được Shoply lưu trữ và không yêu cầu giới hạn ngày.

Ví dụ 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")

Phản hồi mẫu

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

Doanh thu có thể chứa nhiều hơn một loại tiền tệ. Hãy coi revenue là văn bản hiển thị. Sử dụng revenue_usd khi bạn cần giá trị USD đã được chuẩn hóa mà Shoply hiển thị.

Tình huống sử dụng doanh nghiệp

• Gửi bản tóm tắt tác động doanh số hằng ngày cho người bán hoặc đội ngũ thương mại điện tử.
• So sánh lượt tìm kiếm, lượt nhấp sản phẩm, sự kiện thêm vào giỏ và lượt mua để tìm điểm rơi trong phễu chuyển đổi.
• Cung cấp dữ liệu cho dashboard business-intelligence hằng tuần hoặc hằng tháng mà không cần scrape trang Shoply Admin.
• Theo dõi doanh thu được ghi nhận theo thời gian và so sánh với các thay đổi về trưng bày sản phẩm hoặc chiến dịch.

2. Truy xuất múi giờ của cửa hàng

admin_get_store_metadata cung cấp nhãn múi giờ hiển thị trong Analytics → Chat & Search History. Trang này dùng nó để chuyển đổi hoạt động UTC sang giờ địa phương của cửa hàng.

Endpoint

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

Query Parameters

Ví dụ Python

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

Phản hồi mẫu

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

Tình huống sử dụng doanh nghiệp

• Nhóm hoạt động UTC vào cùng các ngày lịch địa phương mà người bán nhìn thấy trong Analytics.
• Lên lịch xuất dữ liệu hằng ngày sau khi ngày địa phương của cửa hàng đã kết thúc.
• Gắn nhãn báo cáo bằng múi giờ IANA rõ ràng như America/Los_Angeles.

Độ lệch múi giờ có thể thay đổi do quy tắc giờ mùa hè. Hãy ưu tiên ianaTimezone khi hệ thống báo cáo của bạn hỗ trợ, thay vì lưu cố định một giá trị lệch số.

3. Truy xuất số lượng hoạt động

query_api_usage_count trả về hoạt động cửa hàng được nhóm theo ngày UTC hoặc theo phút UTC gốc. Đây cũng là nguồn dữ liệu cho biểu đồ hoạt động trong Analytics → Chat & Search History.

Endpoint

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

Query Parameters

Ví dụ 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)

Phản hồi mẫu

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

Các dòng bao gồm các bộ đếm hoạt động có sẵn cho khoảng thời gian đó, như câu hỏi chat, lượt tìm kiếm, lượt nhấp, sự kiện thêm vào giỏ và sự kiện thanh toán. Các bộ đếm không có hoạt động có thể vắng mặt thay vì được đặt bằng không.

Tình huống sử dụng doanh nghiệp

• Xây dựng biểu đồ hoạt động theo giờ hoặc theo ngày giống như trong Chat & Search History.
• Phát hiện các đợt tăng đột biến bất thường về lưu lượng hoặc sự sụt giảm đột ngột trong tương tác của khách hàng.
• So sánh lượng tìm kiếm sản phẩm với lượt nhấp, sự kiện thêm vào giỏ và lượt thanh toán.
• Ước tính thời điểm đội hỗ trợ và đội trưng bày sản phẩm nên xem xét các khoảng thời gian bận rộn nhất.

4. Truy xuất tóm tắt các phiên chat và tìm kiếm

query_sessionized_chat trả về một bản ghi gọn cho mỗi phiên khách hàng. Nó cũng cung cấp dữ liệu cho danh sách phiên trong Analytics → Chat & Search History.

Endpoint

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

Query Parameters

Truy xuất 40 phiên mới nhất

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

Truy xuất các phiên trong một khoảng 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",
)

Khi cả hai mốc thời gian đều có mặt, API trả về các phiên trong toàn bộ khoảng đó; num_sessions không giới hạn truy vấn có giới hạn thời gian này.

Phản hồi mẫu

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

Các trường tùy chọn thay đổi theo từng phiên. Hãy giữ lại customer_id, start_timestamp_ms và end_timestamp_ms nếu bạn dự định truy xuất dòng thời gian đầy đủ.

Tình huống sử dụng doanh nghiệp

• Xem lại mẫu các cuộc hội thoại gần đây để đánh giá chất lượng trả lời và đào tạo hỗ trợ.
• Tìm các câu hỏi lặp lại của khách hàng có thể ảnh hưởng đến nội dung sản phẩm hoặc FAQ.
• Xác định các phiên có ý định mua cao chứa lượt tìm kiếm, lượt nhấp sản phẩm hoặc các hành động mua sắm khác.
• Xuất một dòng cho mỗi phiên để phân tích xu hướng trong khi tránh payload cấp sự kiện lớn hơn.

5. Truy xuất một phiên hoàn chỉnh

Truyền một bản tóm tắt đã chọn vào query_log_visualization để truy xuất các sự kiện của khách hàng, AI, tìm kiếm và thương mại.

Endpoint

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

Query Parameters

Ví dụ 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"))

Phản hồi mẫu

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

Dòng thời gian có thể chứa câu hỏi của khách hàng, câu trả lời của AI, kết quả tìm kiếm, lượt nhấp sản phẩm, sự kiện thêm vào giỏ, sự kiện thanh toán và sự tham gia của nhân viên hỗ trợ. Dùng server_timestamp_ms để sắp xếp các loại sự kiện hỗn hợp. Các bản ghi cũ hơn có thể chứa ít trường hơn.

Tình huống sử dụng doanh nghiệp

• Kiểm tra chính xác khách hàng đã hỏi gì và Shoply đã trả lời gì trong quá trình điều tra hỗ trợ.
• Xem xét chất lượng câu trả lời cùng với kết quả tìm kiếm và sản phẩm đã hiển thị cho người mua.
• Tái dựng hành trình từ câu hỏi đến lượt nhấp, thêm vào giỏ hoặc thanh toán.
• Chẩn đoán một phiên do khách hàng báo cáo mà không cần tìm trong lịch sử không liên quan.

Tôi có thể dùng một secret cho mọi API không?

Có. Một store_owner_api_secrete hợp lệ được giới hạn cho một cửa hàng và hoạt động trên các endpoint Merchant API ở trên. Đối với tài khoản SiteChat, cùng secret đó cũng xác thực cho catalog upload APIs. Để vận hành an toàn hơn, hãy dùng các secret có tên riêng cho các hệ thống riêng biệt — ví dụ, một secret cho xuất dữ liệu hằng đêm và một secret khác cho dashboard nội bộ.

Nếu một tích hợp bị ngừng sử dụng hoặc bị lộ, chỉ cần thu hồi secret của tích hợp đó trong Shoply Settings. Các tích hợp khác sẽ tiếp tục hoạt động.

Tôi nên biết gì về hết hạn, quyền riêng tư và lỗi?

Ngoài ra, hãy xem lại nguồn dữ liệu và quyền riêng tư của Shoply để hiểu thông tin nào có sẵn cho các câu trả lời dành cho khách hàng.

• Secret API của chủ cửa hàng hết hạn sau 90 ngày. Hãy tạo bản thay thế và cập nhật tích hợp trước ngày hết hạn.
• Thời gian lưu trữ tiêu chuẩn cho lịch sử chat và tìm kiếm của Shoply cũng là 90 ngày. Hết hạn secret và lưu giữ dữ liệu là hai chính sách riêng biệt.
• Phản hồi lịch sử có thể chứa dữ liệu cá nhân, bao gồm mã định danh khách hàng, địa chỉ email, vị trí gần đúng, câu hỏi và hoạt động mua sắm. Hãy lưu trữ và xử lý theo chính sách quyền riêng tư của bạn và pháp luật hiện hành.
• HTTP 403 có nghĩa là secret bị thiếu, không hợp lệ, đã hết hạn, đã bị thu hồi hoặc thuộc về một cửa hàng khác.
• HTTP 422 thường có nghĩa là thiếu query parameter bắt buộc hoặc tên tham số bị sai.
• HTTP 500 hoặc phản hồi có statusCode: 500 có nghĩa là yêu cầu đã tới Shoply nhưng không thể hoàn tất. Hãy thử lại các lỗi tạm thời bằng chiến lược backoff và liên hệ với chúng tôi nếu lỗi vẫn tiếp diễn.
• Sử dụng các khoảng UTC có giới hạn cho các tác vụ xuất dữ liệu và công việc lặp lại để phản hồi luôn ở mức có thể quản lý được.

Tìm kiếm sản phẩm có phải là một phần của Merchant API không?

API tìm kiếm sản phẩm công khai của Shoply có cơ chế xác thực và request contract khác. Xem How to Access Shoply AI Search Through the API nếu bạn muốn có kết quả tìm kiếm sản phẩm cho trải nghiệm hướng tới người mua thay vì dữ liệu riêng tư của người bán.

Người bán SiteChat có thể tải lên catalog sản phẩm không?

Có. Tài khoản SiteChat có thể tải lên dữ liệu sản phẩm có cấu trúc và hình ảnh sản phẩm bằng cùng secret API của chủ cửa hàng. Các endpoint catalog đó được mô tả riêng trong How to Upload Your Catalog for SiteChat. Các cửa hàng Shopify tiếp tục đồng bộ sản phẩm thông qua Shopify và không sử dụng các route tải lên đó.

Để được hỗ trợ về tích hợp, liên hệ Shoply AI.