Sut i Ddefnyddio API Masnachwr Shoply

Mae Merchant API Shoply yn caniatáu i fasnachwr ddefnyddio ei ddata Shoply ei hun yn ddiogel mewn offer adrodd, llifoedd gwaith cymorth, allforion wedi’u hamserlennu, a chymwysiadau busnes preifat.

Mae pob integreiddiad yn dilysu gyda chredyn adferadwy, wedi’i gwmpasu i’r siop, a grëir yn Gosodiadau Shoply. Nid oes angen i chi rannu tocyn mynediad Shopify Admin API, a gall integreiddiad gael mynediad at y siop a gyhoeddodd ei gredyn yn unig.

Beth Alla i Ei Wneud Gyda’r Merchant API?

Gallwch ddefnyddio’r Merchant API i:

• Allforio canlyniadau perfformiad dyddiol, wythnosol, neu fisol i daenlen neu warws data.
• Adeiladu dangosfwrdd preifat ar gyfer sesiynau, sgyrsiau, chwiliadau, cliciau cynnyrch, digwyddiadau ychwanegu at y fasged, pryniannau, a refeniw wedi’i briodoli.
• Monitro gweithgarwch cwsmeriaid a darganfod newidiadau anarferol mewn ymgysylltiad.
• Adolygu sesiynau sgwrsio a chwilio ar gyfer cymorth, marchnata nwyddau, a gwaith ansawdd atebion.
• Adfer llinell amser sgwrs unigol wrth ymchwilio i fater cwsmer.
• Creu, diweddaru, rhestru, a dileu’r wybodaeth bersonol a ddefnyddir gan Shoply AI.
• Ychwanegu tudalen we allanol neu ffeil PDF, testun, neu Markdown wedi’i huwchlwytho at y sylfaen wybodaeth.
• Cyfatebu data digwyddiadau UTC â pharth amser lleol y siop.

Mae’r canllaw hwn yn dogfennu saith pwynt terfyn. Mae pump yr un pwyntiau terfyn a ddefnyddir gan Shoply Admin → Analytics, tra bod dau yn rheoli’r sylfaen wybodaeth:

Mae’r cyrff ymateb isod yn samplau cynrychioliadol. Bydd eich meysydd a’ch gwerthoedd yn adlewyrchu’r gweithgarwch a gofnodwyd ar gyfer eich siop.

Gofyniad defnyddio: Rhaid i ddilysiad cyfrinach perchennog siop gael ei ddefnyddio ar y gweinydd API rydych yn ei alw. Os yw cyfrinach ddilys yn dychwelyd HTTP 403 gyda No access_token found, mae’r gweinydd hwnnw’n dal i redeg y cod dilysu hŷn sy’n defnyddio tocyn mynediad yn unig.

Sut Ydw i’n Creu Cyfrinach API?

1. Agorwch eich panel gweinyddu Shoply AI.
2. Ewch i Settings → Store owner API secret.
3. Crëwch gyfrinach a rhowch enw iddi sy’n adnabod yr integreiddiad, fel Weekly reporting export.
4. Copïwch y gyfrinach pan fydd yn ymddangos. Mae Shoply yn dangos y gwerth testun plaen unwaith yn unig.

Mae pob cyfrinach yn ddilys am 90 diwrnod. Gall siop gael cyfrinachau ar wahân ar gyfer integreiddiadau ar wahân, a gallwch ddirymu un gyfrinach heb darfu ar y lleill.

Cadwch y gwerthoedd hyn fel newidynnau amgylchedd ar ochr y gweinydd:

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

Defnyddiwch barth parhaol myshopify.com y siop ar gyfer SHOPLY_STORE_KEY, hyd yn oed os yw siopwyr fel arfer yn ymweld â pharth personol.

Sut Mae Dilysu’n Gweithio?

Mae pob cais Merchant API yn anfon pennyn Authorization y mae ei werth yn llinyn JSON:

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

store_owner_api_secrete yw’r union enw maes cyhoeddus, gan gynnwys ei sillafu hanesyddol. Nid tocyn Bearer yw hwn. Rhowch y llinyn JSON cyflawn yn uniongyrchol yn y pennyn Authorization.

Cadwch y gyfrinach mewn cod cefn yn unig. Peidiwch â’i rhoi mewn URL, bwndel porwr, storfa gyhoeddus, digwyddiad dadansoddeg, na log cymhwysiad.

A Oes Pecynnau Swyddogol Python a Node.js?

Oes. Mae Shoply yn cyhoeddi dau becyn ochr gweinydd sy’n ychwanegu’r dilysiad gofynnol yn awtomatig ac yn datgelu’r Merchant API fel ffwythiannau wedi’u teipio. Mae’r ddau becyn yn ffynhonnell agored o dan sefydliad GitHub shoplyai-public.

Pecyn Python

Mae’r pecyn shoply-merchant-api yn cefnogi Python 3.12 ac yn defnyddio modelau ymateb Pydantic v2. Gosodwch y fersiwn 2.1.3 sydd wedi’i phinio:

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"

Adferwch y sesiynau sgwrsio a chwilio diweddaraf fel modelau SessionSummary wedi’u teipio:

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)

Mae’r pecyn hefyd yn darparu ffwythiannau ar gyfer dadansoddeg, cyfrifiadau gweithgarwch, llinellau amser sesiynau cyflawn, parth amser y siop, a rheoli gwybodaeth. Gweler ei ganllaw achosion defnydd busnes  a’i gyfeirnod API .

Pecyn Node.js a TypeScript

Mae’r storfa shoply-merchant-api-js yn darparu’r pecyn @shoplyai/merchant-api ar gyfer Node.js 20 neu fwy newydd. Mae’n becyn ESM gyda datganiadau TypeScript adeiledig a dim dibyniaethau amser rhedeg. Gosodwch y fersiwn 2.1.3 sydd wedi’i phinio’n uniongyrchol o GitHub:

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

Adferwch yr un sesiynau diweddaraf o weinydd 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);
}

Mae’r pecyn npm yn cwmpasu’r un pwyntiau terfyn Merchant API â’r pecyn Python. Gweler ei ganllaw achosion defnydd busnes  a’i gyfeirnod API .

Mae’r ddau becyn ar gyfer gwasanaethau cefn dibynadwy, swyddi wedi’u hamserlennu, ac offer mewnol preifat. Peidiwch â mewnforio’r naill becyn na’r llall i god blaen y siop na datgelu’r gyfrinach API mewn bwndel porwr.

A Alla i Alw’r HTTP API Heb Becyn?

Gallwch. Mae’r Merchant API yn parhau i fod yn API HTTPS safonol. Mae’r enghreifftiau Python lefel isel isod yn defnyddio Requests fel y gallwch weld y contract gwifren cyflawn neu integreiddio o iaith arall.

Gosodwch Requests os nad yw eich amgylchedd eisoes yn ei gynnwys:

python -m pip install requests

Mae’r cynorthwyydd isod yn ychwanegu allwedd y siop a’r pennyn dilysu at bob cais:

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

Mae’r enghreifftiau isod yn defnyddio’r cleient a rennir hwn. Mae’r ddau gynorthwyydd yn ychwanegu allwedd y siop ddilysedig yn awtomatig.

A Alla i Reoli Gwybodaeth Shoply AI Trwy’r API?

Gallwch. Mae admin_store_knowledge yn defnyddio GET i adfer gwybodaeth a POST i’w chreu, ei diweddaru, ei dileu, neu ei hail-gripian. Mae POST sy’n defnyddio ID gwybodaeth sy’n bodoli eisoes yn diweddaru’r cofnod hwnnw; mae defnyddio ID newydd yn creu un.

Cyn awtomeiddio diweddariadau, cynlluniwch wybodaeth siop ddefnyddiol gyda’r enghreifftiau yn ein canllaw hyfforddi.

Gall ysgrifennu gwybodaeth newid yr atebion a ddangosir i siopwyr. Defnyddiwch gyfrinach benodol ar gyfer y system sy’n rheoli gwybodaeth, dilyswch gynnwys cyn ei anfon, a pheidiwch byth â datgelu’r credyn hwn sydd â gallu ysgrifennu mewn JavaScript blaen y siop.

Rhestru Gwybodaeth Bresennol

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

Ymateb Sampl

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

Creu neu Ddiweddaru Gwybodaeth Testun Personol

Dewiswch ID gwybodaeth sefydlog ac unigryw. Ailddefnyddiwch yr un ID wrth ddiweddaru’r cofnod hwnnw.

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)

Ymateb Sampl

{
  "statusCode": 200
}

Mae ymateb llwyddiannus yn golygu bod y wybodaeth wedi’i chadw. Gall mynegeio chwilio gymryd ychydig funudau, felly efallai na fydd ateb newydd yn ymddangos ar unwaith. Os yw’r API yn adrodd bod y cynnwys wedi’i gadw ond bod mynegeio wedi’i oedi, cadarnhewch y cofnod sydd wedi’i storio gyda GET cyn ail-geisio’r ysgrifennu.

Ychwanegu Tudalen We Allanol

Defnyddiwch ID sy’n dechrau gyda external_url::. Rhowch yr URL cyflawn http:// neu https:// yn 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()),
        }
    },
)

Uwchlwytho a Chofrestru Ffeil Gwybodaeth

Rhaid i ffeiliau gwybodaeth fod yn PDF, TXT, neu Markdown ac yn llai na 5 MB. Uwchlwythwch y ffeil yn gyntaf, yna cadwch y lleoliad S3 preifat a ddychwelwyd fel cofnod gwybodaeth.

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

Ymateb Uwchlwytho Sampl

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

Triniwch file_url fel lleoliad preifat aneglur a ddychwelwyd gan Shoply. Peidiwch â’i lunio na’i newid eich hun.

Dileu Gwybodaeth

Mae dileu yn barhaol. Adferwch y cofnodion cyfredol yn gyntaf ac anfonwch yr union IDau rydych yn bwriadu eu tynnu’n unig.

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

Gofyn am Ail-gripian Gwefan

Defnyddiwch ail-gripian ar ôl i’r cynnwys ar wefan y masnachwr newid. Nid yw fel arfer yn angenrheidiol ar ôl pob diweddariad testun personol.

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

Achosion Defnydd Busnes

• Cydamseru canllawiau cludo, dychweliadau, gwarant, maintio, neu ofal cynnyrch o system gynnwys fewnol.
• Cyhoeddi gwybodaeth ymgyrch dros dro neu wybodaeth gwyliau heb ei chopïo â llaw i Shoply Admin.
• Ychwanegu tudalen we polisi neu ddogfen gymeradwy at y sylfaen wybodaeth fel rhan o lif gwaith defnyddio.
• Dileu canllawiau hen ffasiwn cyn gynted ag y daw polisi neu hyrwyddiad i ben.

Enghreifftiau Merchant API

1. Adfer Dadansoddeg Perfformiad

Mae admin_store_analytics yn pweru’r tabl Analytics → Summary. Mae’n dychwelyd sesiynau, sgyrsiau, chwiliadau, cliciau, digwyddiadau ychwanegu at y fasged, pryniannau, a refeniw wedi’i briodoli.

Pwynt Terfyn

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

Paramedrau Ymholiad

Mae adroddiadau misol yn defnyddio hanes misol storiedig Shoply ac nid oes angen ffiniau dyddiad arnynt.

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

Ymateb Sampl

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

Gall refeniw gynnwys mwy nag un arian cyfred. Triniwch revenue fel testun arddangos. Defnyddiwch revenue_usd pan fo angen y gwerth USD wedi’i normaleiddio a ddangosir gan Shoply.

Achosion Defnydd Busnes

• Anfon crynodeb effaith gwerthiant dyddiol at y masnachwr neu’r tîm ecommerce.
• Cymharu chwiliadau, cliciau cynnyrch, digwyddiadau ychwanegu at y fasged, a phryniannau i ganfod lle mae’r llif yn gollwng.
• Bwydo dangosfwrdd gwybodaeth fusnes wythnosol neu fisol heb sgrapio tudalen Shoply Admin.
• Olrhain refeniw wedi’i briodoli dros amser a’i gymharu â newidiadau marchnata nwyddau neu ymgyrchoedd.

2. Adfer Parth Amser y Siop

Mae admin_get_store_metadata yn darparu’r bathodyn parth amser a ddangosir yn Analytics → Chat & Search History. Mae’r dudalen yn ei ddefnyddio i drosi gweithgarwch UTC i amser lleol y siop.

Pwynt Terfyn

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

Paramedrau Ymholiad

Enghraifft Python

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

Ymateb Sampl

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

Achosion Defnydd Busnes

• Grwpio gweithgarwch UTC i’r un diwrnodau calendr lleol ag a wel y masnachwr yn Analytics.
• Trefnu allforion dyddiol ar ôl i ddiwrnod lleol y siop ddod i ben.
• Labelu adroddiadau gyda pharth amser IANA diamwys fel America/Los_Angeles.

Gall gwrthbwysau parth amser newid oherwydd rheolau amser haf. Ffafriwch ianaTimezone pan fydd eich system adrodd yn ei gefnogi yn lle cadw un gwrthbwysiad rhifiadol yn barhaol.

3. Adfer Cyfrifiadau Gweithgarwch

Mae query_api_usage_count yn dychwelyd gweithgarwch y siop wedi’i grwpio yn ôl dyddiad UTC neu’r funud UTC wreiddiol. Dyma hefyd ffynhonnell y siart gweithgarwch yn Analytics → Chat & Search History.

Pwynt Terfyn

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

Paramedrau Ymholiad

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

Ymateb Sampl

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

Mae rhesi’n cynnwys y cyfrifwyr gweithgarwch sydd ar gael ar gyfer y cyfnod hwnnw, fel cwestiynau sgwrsio, chwiliadau, cliciau, digwyddiadau ychwanegu at y fasged, a digwyddiadau talu. Gall cyfrifwyr heb weithgarwch fod yn absennol yn lle cael eu gosod i sero.

Achosion Defnydd Busnes

• Adeiladu siart gweithgarwch fesul awr neu ddydd fel yr un yn Chat & Search History.
• Canfod pigau traffig anarferol neu ostyngiadau sydyn mewn ymgysylltiad cwsmeriaid.
• Cymharu nifer y chwiliadau cynnyrch â chliciau, digwyddiadau ychwanegu at y fasged, a thaliadau.
• Amcangyfrif pryd y dylai timau cymorth a marchnata nwyddau adolygu’r cyfnodau prysuraf.

4. Adfer Crynodebau Sesiynau Sgwrsio a Chwilio

Mae query_sessionized_chat yn dychwelyd un cofnod cryno fesul sesiwn cwsmer. Mae hefyd yn pweru’r rhestr sesiynau yn Analytics → Chat & Search History.

Pwynt Terfyn

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

Paramedrau Ymholiad

Adfer y 40 Sesiwn Diweddaraf

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

Adfer Sesiynau mewn Ystod 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",
)

Pan fo’r ddau derfyn amser yn bresennol, mae’r API yn dychwelyd sesiynau yn yr ystod gyflawn; nid yw num_sessions yn cyfyngu’r ymholiad wedi’i ffinio hwnnw.

Ymateb Sampl

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

Mae meysydd dewisol yn amrywio yn ôl sesiwn. Cadwch customer_id, start_timestamp_ms, ac end_timestamp_ms os ydych yn bwriadu adfer y llinell amser gyflawn.

Achosion Defnydd Busnes

• Adolygu sampl o sgyrsiau diweddar ar gyfer ansawdd atebion a hyfforddiant cymorth.
• Dod o hyd i gwestiynau cwsmeriaid ailadroddus a ddylai ddylanwadu ar gopi cynnyrch neu Cwestiynau Cyffredin.
• Nodi sesiynau bwriad uchel sy’n cynnwys chwiliadau, cliciau cynnyrch, neu weithredoedd siopa eraill.
• Allforio un rhes fesul sesiwn ar gyfer dadansoddi tueddiadau gan osgoi’r llwyth data mwy ar lefel digwyddiad.

5. Adfer Un Sesiwn Gyflawn

Paswch grynodeb a ddewiswyd i query_log_visualization i adfer ei ddigwyddiadau cwsmer, AI, chwilio, a masnach.

Pwynt Terfyn

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

Paramedrau Ymholiad

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

Ymateb Sampl

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

Gall y llinell amser gynnwys cwestiynau cwsmer, atebion AI, canlyniadau chwilio, cliciau cynnyrch, digwyddiadau ychwanegu at y fasged, digwyddiadau talu, a chyfranogiad asiant dynol. Defnyddiwch server_timestamp_ms i drefnu mathau cymysg o ddigwyddiadau. Gall cofnodion hŷn gynnwys llai o feysydd.

Achosion Defnydd Busnes

• Archwilio’n union beth ofynnodd cwsmer a beth atebodd Shoply yn ystod ymchwiliad cymorth.
• Adolygu ansawdd atebion ynghyd â’r canlyniadau chwilio a’r cynhyrchion a ddangoswyd i’r siopwr.
• Ailadeiladu’r daith o gwestiwn i glic, ychwanegu at y fasged, neu dalu.
• Diagnosio un sesiwn a adroddwyd gan gwsmer heb chwilio trwy hanes anghysylltiedig.

A Alla i Ddefnyddio Un Gyfrinach ar gyfer Pob API?

Gallwch. Mae store_owner_api_secrete dilys wedi’i gwmpasu i un siop ac yn gweithio ar draws pwyntiau terfyn y Merchant API uchod. Ar gyfer cyfrifon SiteChat, mae’r un gyfrinach hefyd yn dilysu catalog upload APIs. Er mwyn gweithrediadau mwy diogel, defnyddiwch gyfrinachau enwedig ar wahân ar gyfer systemau ar wahân—er enghraifft, un ar gyfer allforio data nosol ac un arall ar gyfer dangosfwrdd mewnol.

Os yw un integreiddiad yn cael ei ymddeol neu ei beryglu, dirymwch ei gyfrinach ef yn unig yn Gosodiadau Shoply. Bydd yr integreiddiadau eraill yn parhau i weithio.

Beth Ddylwn i Ei Wybod am Ddod i Ben, Preifatrwydd, a Gwallau?

Hefyd adolygu ffynonellau data a phreifatrwydd Shoply i ddeall pa wybodaeth sydd ar gael i atebion cwsmeriaid.

• Mae cyfrinachau API perchennog siop yn dod i ben ar ôl 90 diwrnod. Crëwch un newydd a diweddarwch yr integreiddiad cyn ei ddyddiad dod i ben.
• Cyfnod cadw hanes safonol Shoply ar gyfer sgwrsio a chwilio hefyd yw 90 diwrnod. Mae dod i ben cyfrinach a chadw data yn bolisïau ar wahân.
• Gall ymatebion hanes gynnwys data personol, gan gynnwys dynodwyr cwsmeriaid, cyfeiriadau e-bost, lleoliad bras, cwestiynau, a gweithgarwch siopa. Storiwch a phroseswch ef yn unol â’ch polisi preifatrwydd a’r gyfraith berthnasol.
• Mae HTTP 403 yn golygu bod y gyfrinach ar goll, yn annilys, wedi dod i ben, wedi’i dirymu, neu’n perthyn i siop wahanol.
• Fel arfer mae HTTP 422 yn golygu bod paramedr ymholiad gofynnol ar goll neu fod ganddo’r enw anghywir.
• Mae HTTP 500 neu ymateb gyda statusCode: 500 yn golygu bod y cais wedi cyrraedd Shoply ond na ellid ei gwblhau. Ailgeisiwch fethiannau dros dro gyda backoff a chysylltwch â ni os yw’r gwall yn parhau.
• Defnyddiwch ystodau UTC wedi’u ffinio ar gyfer allforion a swyddi cylchol fel bod ymatebion yn aros yn hylaw.

A Yw Chwilio Cynnyrch yn Rhan o’r Merchant API?

Mae API chwilio cynnyrch cyhoeddus Shoply yn defnyddio contract dilysu a chais gwahanol. Gweler How to Access Shoply AI Search Through the API os ydych eisiau canlyniadau chwilio cynnyrch ar gyfer profiad sy’n wynebu siopwyr yn hytrach na data preifat masnachwr.

A All Masnachwyr SiteChat Uwchlwytho Catalog Cynnyrch?

Gallant. Gall cyfrifon SiteChat uwchlwytho cynhyrchion strwythuredig a delweddau cynnyrch gyda’r un gyfrinach API perchennog siop. Mae’r pwyntiau terfyn catalog hynny wedi’u dogfennu ar wahân yn How to Upload Your Catalog for SiteChat. Mae siopau Shopify yn parhau i gysoni cynhyrchion trwy Shopify ac nid ydynt yn defnyddio’r llwybrau uwchlwytho hynny.

Am gymorth gydag integreiddiad, cysylltwch â Shoply AI.