Как да използвате Shoply Merchant API

Shoply Merchant API позволява на търговеца сигурно да използва собствените си данни от Shoply в инструменти за отчетност, работни процеси за поддръжка, планирани експорти и частни бизнес приложения.

Всяка интеграция се удостоверява чрез отменяем идентификационен ключ с обхват до конкретен магазин, създаден в Shoply Settings. Не е необходимо да споделяте Shopify Admin API access token, а една интеграция може да достъпва само магазина, който е издал нейния идентификационен ключ.

Какво мога да правя с Merchant API?

Можете да използвате Merchant API, за да:

• Експортирате дневни, седмични или месечни резултати за ефективност към електронна таблица или хранилище за данни.
• Изградите частно табло за сесии, чатове, търсения, кликвания върху продукти, събития за добавяне в количката, покупки и приписани приходи.
• Следите активността на клиентите и да откривате необичайни промени в ангажираността.
• Преглеждате чат и search сесии за поддръжка, мърчандайзинг и работа по качеството на отговорите.
• Извличате хронологията на отделен разговор при разследване на клиентски проблем.
• Създавате, актуализирате, изброявате и изтривате custom knowledge, използвано от Shoply AI.
• Добавяте външна уеб страница или качен PDF, текстов или Markdown файл към knowledge base.
• Съгласувате UTC данни за събитията с локалната часова зона на магазина.

Това ръководство документира седем endpoint-а. Пет са същите endpoint-и, използвани от Shoply Admin → Analytics, а два управляват knowledge base:

Телата на отговорите по-долу са примерни. Вашите полета и стойности ще отразяват активността, записана за вашия магазин.

Изискване за внедряване: Удостоверяването със secret на собственика на магазина трябва да е внедрено на API сървъра, който извиквате. Ако валиден secret връща HTTP 403 с No access_token found, този сървър все още работи с по-стария код за удостоверяване само чрез access token.

Как да създам API secret?

1. Отворете вашия Shoply AI admin.
2. Отидете на Settings → Store owner API secret.
3. Създайте secret и му дайте име, което идентифицира интеграцията, например Weekly reporting export.
4. Копирайте secret-а, когато се появи. Shoply показва стойността в чист текст само веднъж.

Всеки secret е валиден 90 дни. Един магазин може да има отделни secret-и за отделни интеграции и можете да отмените един secret, без да прекъсвате останалите.

Запазете тези стойности като server-side environment variables:

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

Използвайте постоянния myshopify.com домейн на магазина за SHOPLY_STORE_KEY, дори ако клиентите обикновено посещават custom домейн.

Как работи удостоверяването?

Всяка заявка към Merchant API изпраща Authorization header, чиято стойност е JSON низ:

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

store_owner_api_secrete е точното публично име на полето, включително историческия му правопис. Това не е Bearer token. Поставете целия JSON низ директно в Authorization header.

Пазете secret-а само в backend кода. Не го поставяйте в URL, browser bundle, публично хранилище, analytics събитие или application log.

Има ли официални Python и Node.js пакети?

Да. Shoply публикува два server-side пакета, които автоматично добавят необходимото удостоверяване и предоставят Merchant API като типизирани функции. И двата пакета са open source под GitHub организацията shoplyai-public.

Python пакет

Пакетът shoply-merchant-api поддържа Python 3.12 и използва Pydantic v2 модели за отговор. Инсталирайте фиксираната версия 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"

Извлечете най-новите чат и search сесии като типизирани модели 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)

Пакетът също предоставя функции за analytics, броячи на активност, пълни хронологии на сесии, часовата зона на магазина и управление на knowledge. Вижте неговото ръководство за бизнес случаи на употреба  и API reference .

Пакет за Node.js и TypeScript

Хранилището shoply-merchant-api-js предоставя пакета @shoplyai/merchant-api за Node.js 20 или по-нова версия. Това е ESM пакет с вградени TypeScript декларации и без runtime зависимости. Инсталирайте фиксираната версия 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 пакетът покрива същите Merchant API endpoint-и като Python пакета. Вижте неговото ръководство за бизнес случаи на употреба  и API reference .

И двата пакета са за доверени backend услуги, планирани задачи и частни вътрешни инструменти. Не импортирайте нито един от пакетите в storefront код и не излагайте API secret в browser bundle.

Мога ли да извиквам HTTP API без пакет?

Да. Merchant API остава стандартен HTTPS API. Ниското ниво на Python примерите по-долу използва Requests, за да можете да видите пълния wire contract или да интегрирате от друг език.

Инсталирайте Requests, ако средата ви все още не го включва:

python -m pip install requests

Помощната функция по-долу добавя 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

Примерите по-долу използват този споделен клиент. И двете помощни функции автоматично добавят удостоверения store key.

Мога ли да управлявам Shoply AI knowledge чрез API?

Да. admin_store_knowledge използва GET за извличане на knowledge и POST за създаване, актуализиране, изтриване или повторното му обхождане. POST, който използва съществуващ knowledge ID, актуализира този запис; използването на нов ID създава нов.

Преди да автоматизирате актуализациите, планирайте полезно knowledge за магазина с примерите в нашето ръководство за обучение.

Записите в knowledge могат да променят отговорите, показвани на клиентите. Използвайте отделен secret за системата, която управлява knowledge, валидирайте съдържанието преди изпращане и никога не излагайте този идентификационен ключ с права за запис в storefront JavaScript.

Списък на съществуващо knowledge

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

Създаване или актуализиране на custom text knowledge

Изберете стабилен, уникален 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
}

Успешен отговор означава, че knowledge е запазено. Индексирането за търсене може да отнеме няколко минути, така че нов отговор може да не се появи веднага. Ако API съобщи, че съдържанието е запазено, но индексирането се бави, потвърдете запазения запис с GET, преди да опитате отново записа.

Добавяне на външна уеб страница

Използвайте ID, започващ с external_url::. Поставете пълния http:// или https:// URL в 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()),
        }
    },
)

Качване и регистриране на knowledge файл

Knowledge файловете трябва да са PDF, TXT или Markdown и да са по-малки от 5 MB. Първо качете файла, след това запазете върнатото частно S3 местоположение като knowledge запис.

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. Не го конструирайте и не го променяйте сами.

Изтриване на knowledge

Изтриването е постоянно. Първо извлечете текущите записи и изпратете само точните ID-та, които възнамерявате да премахнете.

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

Заявка за повторно обхождане на уебсайт

Използвайте повторно обхождане, след като съдържанието на уебсайта на търговеца се промени. Обикновено не е необходимо след всяка актуализация на custom text.

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

Бизнес случаи на употреба

• Синхронизирайте насоки за доставка, връщане, гаранция, размери или грижа за продукта от вътрешна система за съдържание.
• Публикувайте временна информация за кампании или празници, без ръчно да я копирате в Shoply Admin.
• Добавете страница с политики или одобрен документ към knowledge base като част от deployment workflow.
• Премахвайте остарели насоки веднага щом дадена политика или промоция приключи.

Примери за Merchant API

1. Извличане на analytics за ефективност

admin_store_analytics захранва таблицата Analytics → Summary. Той връща сесии, чатове, търсения, кликвания, събития за добавяне в количката, покупки и приписани приходи.

Endpoint

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

Параметри на заявката

Месечните отчети използват съхранената месечна история на 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 екипа.
• Сравнявайте търсения, кликвания върху продукти, събития за добавяне в количката и покупки, за да откриете отпадане по фунията.
• Захранвайте седмично или месечно табло за business intelligence, без да scraping-вате страницата на Shoply Admin.
• Проследявайте приписаните приходи във времето и ги сравнявайте с промени в мърчандайзинга или кампаниите.

2. Извличане на часовата зона на магазина

admin_get_store_metadata предоставя обозначението за часова зона, показвано в Analytics → Chat & Search History. Страницата го използва, за да превежда UTC активността в локалното време на магазина.

Endpoint

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

Параметри на заявката

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

Параметри на заявката

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.
• Откривайте необичайни пикове в трафика или внезапни спадове в ангажираността на клиентите.
• Сравнявайте обема на product search с кликвания, събития за добавяне в количката и checkout-и.
• Преценявайте кога екипите по поддръжка и мърчандайзинг трябва да преглеждат най-натоварените периоди.

4. Извличане на обобщения на чат и search сесии

query_sessionized_chat връща по един компактен запис за всяка клиентска сесия. Той също захранва списъка със сесии в Analytics → Chat & Search History.

Endpoint

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

Параметри на заявката

Извличане на последните 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 не ограничава тази ограничена по време заявка.

Примерен отговор

{
  "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, ако планирате да извлечете пълната хронология.

Бизнес случаи на употреба

• Преглеждайте извадка от скорошни разговори за качество на отговорите и обучение на екипа по поддръжка.
• Откривайте повтарящи се клиентски въпроси, които трябва да повлияят на описанията на продукти или FAQ.
• Идентифицирайте сесии с висок интент, съдържащи търсения, кликвания върху продукти или други shopping действия.
• Експортирайте по един ред на сесия за анализ на тенденции, като избягвате по-големия payload на ниво събитие.

5. Извличане на една пълна сесия

Подайте избрано обобщение към query_log_visualization, за да извлечете неговите събития за клиент, AI, търсене и commerce.

Endpoint

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

Параметри на заявката

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 и участие на човешки агент. Използвайте server_timestamp_ms, за да подредите смесени типове събития. По-старите записи може да съдържат по-малко полета.

Бизнес случаи на употреба

• Проверявайте точно какво е попитал клиентът и какво е отговорил Shoply по време на разследване от поддръжката.
• Преглеждайте качеството на отговорите заедно с резултатите от търсенето и продуктите, показани на клиента.
• Възстановявайте пътя от въпрос до кликване, добавяне в количката или checkout.
• Диагностицирайте една сесия, докладвана от клиент, без да търсите в несвързана история.

Мога ли да използвам един secret за всяко API?

Да. Валиден store_owner_api_secrete е ограничен до един магазин и работи за endpoint-ите на Merchant API по-горе. За SiteChat акаунти същият secret удостоверява и API-тата за качване на каталог. За по-безопасни операции използвайте отделни именувани secret-и за отделни системи — например един за нощен експорт на данни и друг за вътрешно табло.

Ако една интеграция бъде спряна или компрометирана, отменете само нейния secret в Shoply Settings. Останалите интеграции ще продължат да работят.

Какво трябва да знам за изтичането, поверителността и грешките?

Също така прегледайте източниците на данни и поверителността в Shoply, за да разберете коя информация е достъпна за клиентските отговори.

• API secret-ите на собственика на магазина изтичат след 90 дни. Създайте заместващ и актуализирайте интеграцията преди датата му на изтичане.
• Стандартният период за съхранение на историята на чат и търсене в Shoply също е 90 дни. Изтичането на secret и съхранението на данни са отделни политики.
• Отговорите с история могат да съдържат лични данни, включително клиентски идентификатори, имейл адреси, приблизително местоположение, въпроси и shopping активност. Съхранявайте и обработвайте тези данни според вашата политика за поверителност и приложимото законодателство.
• HTTP 403 означава, че secret-ът липсва, е невалиден, изтекъл, отменен или принадлежи на друг магазин.
• HTTP 422 обикновено означава, че липсва задължителен query parameter или че е с грешно име.
• HTTP 500 или отговор с statusCode: 500 означава, че заявката е достигнала Shoply, но не е могла да бъде изпълнена. Повтаряйте временните неуспехи с backoff и се свържете с нас, ако грешката продължава.
• Използвайте ограничени UTC диапазони за експорти и повтарящи се задачи, за да останат отговорите управляеми.

Част ли е product search от Merchant API?

Публичното product-search API на Shoply има различен договор за удостоверяване и заявки. Вижте Как да получите достъп до Shoply AI Search чрез API, ако искате резултати от product search за клиентско изживяване, а не частни данни на търговеца.

Могат ли SiteChat търговците да качват продуктов каталог?

Да. SiteChat акаунтите могат да качват структурирани продукти и продуктови изображения със същия API secret на собственика на магазина. Тези endpoint-и за каталог са документирани отделно в Как да качите своя каталог за SiteChat. Shopify магазините продължават да синхронизират продуктите чрез Shopify и не използват тези маршрути за качване.

За помощ с интеграция свържете се с Shoply AI.