Shoply Merchant API:n käyttö

Shoply Merchant API antaa kauppiaalle mahdollisuuden käyttää turvallisesti omia Shoply-tietojaan raportointityökaluissa, tukityönkuluissa, ajastetuissa viennissä ja yksityisissä liiketoimintasovelluksissa.

Jokainen integraatio tunnistautuu peruttavalla, kauppakohtaisella tunnisteella, joka luodaan Shoplyn asetuksissa. Sinun ei tarvitse jakaa Shopify Admin API -käyttötunnusta, ja integraatio voi käyttää vain sitä kauppaa, joka myönsi sille tunnisteen.

Mitä voin tehdä Merchant API:n avulla?

Voit käyttää Merchant APIa seuraaviin tarkoituksiin:

• Viedä päivittäisiä, viikoittaisia tai kuukausittaisia tuloksia taulukkolaskentaan tai tietovarastoon.
• Rakentaa yksityisen hallintapaneelin sessioille, keskusteluille, hauille, tuoteklikkauksille, ostoskoriin lisäämisille, ostoille ja kohdistetulle liikevaihdolle.
• Seurata asiakkaiden toimintaa ja havaita poikkeavia muutoksia sitoutumisessa.
• Tarkastella keskustelu- ja hakusessioita tuen, merchandisingin ja vastausten laadun arvioinnin tarpeisiin.
• Hakea yksittäisen keskustelun aikajanan asiakasongelman selvittämistä varten.
• Luoda, päivittää, listata ja poistaa Shoply AI:n käyttämää mukautettua tietämystä.
• Lisätä ulkoinen verkkosivu tai ladattu PDF-, teksti- tai Markdown-tiedosto tietopohjaan.
• Sovittaa UTC-tapahtumatiedot kaupan paikalliseen aikavyöhykkeeseen.

Tässä oppaassa dokumentoidaan seitsemän endpointia. Viisi niistä ovat samoja endpointteja, joita käyttää Shoply Admin → Analytics, ja kaksi hallinnoivat tietopohjaa:

Alla olevat vastaukset ovat edustavia esimerkkejä. Omat kenttäsi ja arvosi heijastavat kauppaasi tallennettua toimintaa.

Käyttöönottoa koskeva vaatimus: Kaupan omistajan salaisuuteen perustuvan tunnistautumisen on oltava käytössä kutsumallasi API-palvelimella. Jos kelvollinen salaisuus palauttaa HTTP 403 vastauksen, jossa lukee No access_token found, kyseinen palvelin käyttää yhä vanhempaa tunnistautumiskoodia, joka tukee vain access tokenia.

Miten luon API-salaisuuden?

1. Avaa Shoply AI -ylläpitopaneelisi.
2. Siirry kohtaan Settings → Store owner API secret.
3. Luo salaisuus ja anna sille integraation tunnistava nimi, kuten Weekly reporting export.
4. Kopioi salaisuus, kun se näytetään. Shoply näyttää selväkielisen arvon vain kerran.

Jokainen salaisuus on voimassa 90 päivää. Kaupalla voi olla erilliset salaisuudet eri integraatioille, ja voit perua yhden salaisuuden keskeyttämättä muita.

Tallenna nämä arvot palvelinpuolen ympäristömuuttujiin:

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

Käytä SHOPLY_STORE_KEY-arvona kaupan pysyvää myshopify.com-verkkotunnusta, vaikka asiakkaat käyttäisivät tavallisesti mukautettua verkkotunnusta.

Miten tunnistautuminen toimii?

Jokainen Merchant API -pyyntö lähettää Authorization-otsakkeen, jonka arvo on JSON-merkkijono:

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

store_owner_api_secrete on täsmälleen oikea julkinen kenttänimi, mukaan lukien sen historiallinen kirjoitusasu. Tämä ei ole Bearer-token. Aseta koko JSON-merkkijono suoraan Authorization-otsakkeeseen.

Pidä salaisuus vain backend-koodissa. Älä sijoita sitä URL-osoitteeseen, selainbundleen, julkiseen repositorioon, analytiikkatapahtumaan tai sovelluslokiin.

Onko olemassa virallisia Python- ja Node.js-paketteja?

Kyllä. Shoply julkaisee kaksi palvelinpuolen pakettia, jotka lisäävät vaaditun tunnistautumisen automaattisesti ja tarjoavat Merchant API:n tyypitettyinä funktioina. Molemmat paketit ovat avointa lähdekoodia shoplyai-public GitHub-organisaation alla.

Python-paketti

shoply-merchant-api -paketti tukee Python 3.12:ta ja käyttää Pydantic v2 -vastemalleja. Asenna kiinnitetty 2.1.3-julkaisu:

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"

Hae uusimmat keskustelu- ja hakusessiot tyypitettyinä SessionSummary-malleina:

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)

Paketti tarjoaa myös funktiot analytiikalle, toimintamäärille, täydellisille session aikajanoille, kaupan aikavyöhykkeelle ja tietämyksen hallinnalle. Katso sen business-use-case guide  ja API reference .

Node.js- ja TypeScript-paketti

shoply-merchant-api-js -repositorio tarjoaa @shoplyai/merchant-api-paketin Node.js 20:lle tai uudemmalle. Se on ESM-paketti, jossa on sisäänrakennetut TypeScript-määritykset eikä lainkaan runtime-riippuvuuksia. Asenna kiinnitetty 2.1.3-julkaisu suoraan GitHubista:

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

Hae samat uusimmat sessiot Node.js-palvelimelta:

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-paketti kattaa samat Merchant API -endpointit kuin Python-paketti. Katso sen business-use-case guide  ja API reference .

Molemmat paketit on tarkoitettu luotetuille backend-palveluille, ajastetuille töille ja yksityisille sisäisille työkaluille. Älä tuo kumpaakaan pakettia storefront-koodiin äläkä paljasta API-salaisuutta selainbundlessa.

Voinko kutsua HTTP APIa ilman pakettia?

Kyllä. Merchant API on edelleen tavallinen HTTPS API. Alla olevat matalan tason Python-esimerkit käyttävät Requests-kirjastoa, jotta näet koko siirtosopimuksen tai voit integroida toisesta ohjelmointikielestä.

Asenna Requests, jos ympäristösi ei vielä sisällä sitä:

python -m pip install requests

Alla oleva apufunktio lisää kauppa-avaimen ja tunnistautumisotsakkeen jokaiseen pyyntöön:

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

Alla olevat esimerkit käyttävät tätä yhteistä asiakasta. Molemmat apufunktiot lisäävät tunnistetun kauppa-avaimen automaattisesti.

Voinko hallita Shoply AI:n tietämystä API:n kautta?

Kyllä. admin_store_knowledge käyttää GET-metodia tietämyksen hakemiseen ja POST-metodia sen luomiseen, päivittämiseen, poistamiseen tai uudelleenindeksointiin. POST, joka käyttää olemassa olevaa tietämys-ID:tä, päivittää kyseisen merkinnän; uuden ID:n käyttö luo uuden.

Ennen kuin automatisoit päivityksiä, suunnittele hyödyllinen kaupan tietämys koulutusoppaamme esimerkkien avulla.

Tietämyksen kirjoitukset voivat muuttaa ostajille näytettäviä vastauksia. Käytä erillistä salaisuutta järjestelmälle, joka hallitsee tietämystä, validoi sisältö ennen lähettämistä äläkä koskaan paljasta tätä kirjoitusoikeudellista tunnistetta storefront-JavaScriptissä.

Listaa olemassa oleva tietämys

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

Esimerkkivastaus

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

Luo tai päivitä mukautettua tekstimuotoista tietämystä

Valitse vakaa ja yksilöllinen tietämys-ID. Käytä samaa ID:tä uudelleen, kun päivität kyseistä merkintää.

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)

Esimerkkivastaus

{
  "statusCode": 200
}

Onnistunut vastaus tarkoittaa, että tietämys tallennettiin. Haun indeksointi voi kestää muutaman minuutin, joten uusi vastaus ei välttämättä näy heti. Jos API ilmoittaa, että sisältö tallennettiin mutta indeksointi viivästyy, varmista tallennettu merkintä GET-pyynnöllä ennen kirjoitusyrityksen uusimista.

Lisää ulkoinen verkkosivu

Käytä ID:tä, joka alkaa merkkijonolla external_url::. Aseta täydellinen http://- tai https://-URL text-kenttään.

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

Lataa ja rekisteröi tietämystiedosto

Tietämystiedostojen on oltava PDF-, TXT- tai Markdown-muotoisia ja kooltaan alle 5 Mt. Lataa tiedosto ensin ja tallenna sitten palautettu yksityinen S3-sijainti tietämysmerkinnäksi.

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

Esimerkkivastaus latauksesta

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

Käsittele file_url-arvoa Shoplyn palauttamana läpinäkymättömänä yksityisenä sijaintina. Älä muodosta tai muuta sitä itse.

Poista tietämys

Poistaminen on pysyvää. Hae nykyiset merkinnät ensin ja lähetä vain täsmälleen ne ID:t, jotka aiot poistaa.

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

Pyydä verkkosivun uudelleenindeksointia

Käytä uudelleenindeksointia sen jälkeen, kun kauppiaan verkkosivun sisältö muuttuu. Se ei yleensä ole tarpeen jokaisen mukautetun tekstipäivityksen jälkeen.

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

Liiketoiminnan käyttötapauksia

• Synkronoi toimitus-, palautus-, takuu-, mitoitus- tai tuotteenhoito-ohjeet sisäisestä sisältöjärjestelmästä.
• Julkaise väliaikaista kampanja- tai sesonkitietoa ilman manuaalista kopiointia Shoply Adminiin.
• Lisää käytäntösivu tai hyväksytty dokumentti tietopohjaan osana käyttöönottotyönkulkua.
• Poista vanhentunut ohjeistus heti, kun käytäntö tai kampanja päättyy.

Merchant API -esimerkkejä

1. Hae suorituskykyanalytiikka

admin_store_analytics käyttää Analytics → Summary -taulukkoa. Se palauttaa sessiot, keskustelut, haut, klikkaukset, ostoskoriin lisäämiset, ostot ja kohdistetun liikevaihdon.

Endpoint

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

Kyselyparametrit

Kuukausiraportit käyttävät Shoplyn tallennettua kuukausihistoriaa eivätkä vaadi päivämäärärajoja.

Python-esimerkki

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

Esimerkkivastaus

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

Liikevaihto voi sisältää useamman kuin yhden valuutan. Käsittele revenue-kenttää näyttötekstinä. Käytä revenue_usd-kenttää, kun tarvitset Shoplyn näyttämän normalisoidun USD-arvon.

Liiketoiminnan käyttötapauksia

• Lähetä päivittäinen myyntivaikutuksen yhteenveto kauppiaalle tai verkkokauppatiimille.
• Vertaa hakuja, tuoteklikkauksia, ostoskoriin lisäämisiä ja ostoja löytääksesi suppilon pudotuskohdat.
• Syötä viikoittainen tai kuukausittainen business intelligence -hallintapaneeli ilman Shoply Admin -sivun skrappausta.
• Seuraa kohdistettua liikevaihtoa ajan mittaan ja vertaa sitä merchandising- tai kampanjamuutoksiin.

2. Hae kaupan aikavyöhyke

admin_get_store_metadata toimittaa aikavyöhykemerkin, joka näytetään kohdassa Analytics → Chat & Search History. Sivu käyttää sitä UTC-toiminnan muuntamiseen kaupan paikalliseen aikaan.

Endpoint

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

Kyselyparametrit

Python-esimerkki

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

Esimerkkivastaus

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

Liiketoiminnan käyttötapauksia

• Ryhmittele UTC-toiminta samoihin paikallisiin kalenteripäiviin, jotka kauppias näkee Analyticsissa.
• Ajasta päivittäiset viennit sen jälkeen, kun kaupan paikallinen päivä on päättynyt.
• Merkitse raportit yksiselitteisellä IANA-aikavyöhykkeellä, kuten America/Los_Angeles.

Aikavyöhyke-offsetit voivat muuttua kesäaikasääntöjen vuoksi. Suosi ianaTimezone-kenttää silloin, kun raportointijärjestelmäsi tukee sitä, sen sijaan että tallentaisit pysyvästi yhden numeerisen offsetin.

3. Hae toimintamäärät

query_api_usage_count palauttaa kaupan toiminnan ryhmiteltynä UTC-päivän tai alkuperäisen UTC-minuutin mukaan. Se on myös Analytics → Chat & Search History -näkymän toimintakaavion lähde.

Endpoint

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

Kyselyparametrit

Python-esimerkki

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)

Esimerkkivastaus

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

Rivit sisältävät kyseiselle ajanjaksolle saatavilla olevat toimintalaskurit, kuten keskustelukysymykset, haut, klikkaukset, ostoskoriin lisäämiset ja checkout-tapahtumat. Laskurit, joissa ei ole toimintaa, voivat puuttua sen sijaan, että ne olisi asetettu nollaksi.

Liiketoiminnan käyttötapauksia

• Rakenna tunneittainen tai päivittäinen toimintakaavio kuten Chat & Search History -näkymässä.
• Havaitse poikkeavat liikennepiikit tai äkilliset pudotukset asiakkaiden sitoutumisessa.
• Vertaa tuotehakujen määrää klikkauksiin, ostoskoriin lisäämisiin ja checkout-tapahtumiin.
• Arvioi, milloin tuki- ja merchandising-tiimien kannattaa tarkastella kiireisimpiä ajanjaksoja.

4. Hae keskustelu- ja hakusessioiden yhteenvedot

query_sessionized_chat palauttaa yhden tiiviin tietueen per asiakassessio. Se käyttää myös session listaa kohdassa Analytics → Chat & Search History.

Endpoint

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

Kyselyparametrit

Hae viimeisimmät 40 sessiota

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

Hae sessiot UTC-aikaväliltä

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

Kun molemmat aikarajat ovat mukana, API palauttaa sessiot koko alueelta; num_sessions ei rajoita tätä rajattua kyselyä.

Esimerkkivastaus

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

Valinnaiset kentät vaihtelevat session mukaan. Säilytä customer_id, start_timestamp_ms ja end_timestamp_ms, jos aiot hakea täydellisen aikajanan.

Liiketoiminnan käyttötapauksia

• Tarkastele otosta viimeaikaisista keskusteluista vastausten laadun ja tukikoulutuksen vuoksi.
• Löydä toistuvat asiakaskysymykset, joiden tulisi vaikuttaa tuotekuvauksiin tai UKK-sisältöön.
• Tunnista korkean ostoaikeen sessiot, jotka sisältävät hakuja, tuoteklikkauksia tai muita ostotoimintoja.
• Vie yksi rivi per sessio trendianalyysiä varten välttäen suurempaa tapahtumatason kuormaa.

5. Hae yksi täydellinen sessio

Välitä valittu yhteenveto query_log_visualization-endpointille hakeaksesi sen asiakas-, AI-, haku- ja kaupankäyntitapahtumat.

Endpoint

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

Kyselyparametrit

Python-esimerkki

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

Esimerkkivastaus

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

Aikajana voi sisältää asiakkaan kysymyksiä, AI-vastauksia, hakutuloksia, tuoteklikkauksia, ostoskoriin lisäämisiä, checkout-tapahtumia ja ihmispalvelijan osallistumista. Käytä server_timestamp_ms-kenttää erilaisten tapahtumatyyppien järjestämiseen. Vanhemmat tietueet voivat sisältää vähemmän kenttiä.

Liiketoiminnan käyttötapauksia

• Auditoi tarkasti, mitä asiakas kysyi ja mitä Shoply vastasi tukiselvityksen aikana.
• Tarkastele vastausten laatua yhdessä ostajalle näytettyjen hakutulosten ja tuotteiden kanssa.
• Rakenna uudelleen polku kysymyksestä klikkaukseen, ostoskoriin lisäämiseen tai checkoutiin.
• Diagnosoi asiakkaan ilmoittama yksittäinen sessio ilman, että joudut etsimään asiaan liittymättömästä historiasta.

Voinko käyttää yhtä salaisuutta kaikille APIeille?

Kyllä. Kelvollinen store_owner_api_secrete on rajattu yhteen kauppaan ja toimii kaikissa yllä olevissa Merchant API -endpointeissa. SiteChat-tileillä sama salaisuus tunnistaa myös catalog upload APIs. Turvallisempaa käyttöä varten käytä erillisiä nimettyjä salaisuuksia eri järjestelmille — esimerkiksi yksi yöaikaiseen tietovientiin ja toinen sisäiseen hallintapaneeliin.

Jos yksi integraatio poistetaan käytöstä tai vaarantuu, peruuta vain sen salaisuus Shoplyn asetuksissa. Muut integraatiot jatkavat toimintaansa.

Mitä minun pitäisi tietää vanhenemisesta, yksityisyydestä ja virheistä?

Tutustu myös Shoplyn tietolähteisiin ja yksityisyyteen, jotta ymmärrät, mitä tietoja asiakasvastauksissa voi olla käytettävissä.

• Kaupan omistajan API-salaisuudet vanhenevat 90 päivän jälkeen. Luo korvaava salaisuus ja päivitä integraatio ennen sen vanhenemispäivää.
• Shoplyn vakio keskustelu- ja hakuhistorian säilytysaika on myös 90 päivää. Salaisuuden vanheneminen ja tietojen säilytys ovat erillisiä käytäntöjä.
• Historiavastaukset voivat sisältää henkilötietoja, mukaan lukien asiakastunnisteita, sähköpostiosoitteita, likimääräisen sijainnin, kysymyksiä ja ostostoimintaa. Säilytä ja käsittele niitä tietosuojakäytäntösi ja sovellettavan lain mukaisesti.
• HTTP 403 tarkoittaa, että salaisuus puuttuu, on virheellinen, vanhentunut, peruttu tai kuuluu eri kaupalle.
• HTTP 422 tarkoittaa yleensä, että pakollinen kyselyparametri puuttuu tai sen nimi on väärä.
• HTTP 500 tai vastaus, jossa on statusCode: 500, tarkoittaa, että pyyntö saavutti Shoplyn mutta sitä ei voitu suorittaa loppuun. Yritä tilapäisiä virheitä uudelleen backoff-strategialla ja ota meihin yhteyttä, jos virhe jatkuu.
• Käytä rajattuja UTC-aikavälejä vienneissä ja toistuvissa töissä, jotta vastaukset pysyvät hallittavan kokoisina.

Onko tuotehaku osa Merchant APIa?

Shoplyn julkisella tuotehaku-APIlla on erilainen tunnistautuminen ja pyyntösopimus. Katso How to Access Shoply AI Search Through the API, jos haluat ostajalle näkyviä tuotehakutuloksia yksityisen kauppiastiedon sijaan.

Voivatko SiteChat-kauppiaat ladata tuotekatalogin?

Kyllä. SiteChat-tilit voivat ladata rakenteellisia tuotteita ja tuotekuvia samalla kaupan omistajan API-salaisuudella. Nämä katalogiendpointit on dokumentoitu erikseen kohdassa How to Upload Your Catalog for SiteChat. Shopify-kaupat jatkavat tuotteiden synkronointia Shopifyn kautta eivätkä käytä näitä latausreittejä.

Jos tarvitset apua integraation kanssa, ota yhteyttä Shoply AI:hin.