Как использовать Merchant API Shoply

Merchant API Shoply позволяет продавцу безопасно использовать собственные данные Shoply в инструментах отчетности, процессах поддержки, запланированных экспортов и приватных бизнес-приложениях.

Каждая интеграция проходит аутентификацию с помощью отзываемых учетных данных, привязанных к конкретному магазину и созданных в настройках Shoply. Вам не нужно делиться токеном доступа Shopify Admin API, и интеграция может получить доступ только к тому магазину, который выпустил свои учетные данные.

Что можно делать с Merchant API?

Вы можете использовать Merchant API, чтобы:

• Экспортировать ежедневные, еженедельные или ежемесячные результаты эффективности в таблицу или хранилище данных.
• Создать приватную панель мониторинга для сессий, чатов, поисков, кликов по товарам, событий добавления в корзину, покупок и атрибутированной выручки.
• Отслеживать активность клиентов и выявлять необычные изменения во вовлеченности.
• Проверять сессии чата и поиска для задач поддержки, мерчандайзинга и контроля качества ответов.
• Получать временную шкалу отдельного диалога при расследовании проблемы клиента.
• Создавать, обновлять, перечислять и удалять пользовательские знания, используемые Shoply AI.
• Добавлять внешнюю веб-страницу или загруженный PDF-, текстовый или Markdown-файл в базу знаний.
• Сопоставлять данные событий в UTC с локальным часовым поясом магазина.

В этом руководстве описаны семь endpoint’ов. Пять из них — это те же endpoint’ы, которые используются в Shoply Admin → Analytics, а два предназначены для управления базой знаний:

Ниже приведены типовые примеры тел ответов. Ваши поля и значения будут отражать активность, зафиксированную для вашего магазина.

Требование к развертыванию: Аутентификация по секрету владельца магазина должна быть развернута на API-сервере, к которому вы обращаетесь. Если действительный секрет возвращает HTTP 403 с No access_token found, значит на этом сервере все еще работает старый код аутентификации только по access token.

Как создать секрет API?

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

Каждый секрет действует 90 дней. Магазин может иметь отдельные секреты для отдельных интеграций, и вы можете отозвать один секрет, не прерывая работу остальных.

Сохраните эти значения как серверные переменные окружения:

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

Для SHOPLY_STORE_KEY используйте постоянный домен магазина myshopify.com, даже если покупатели обычно заходят через пользовательский домен.

Как работает аутентификация?

Каждый запрос Merchant API отправляет заголовок Authorization, значением которого является JSON-строка:

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

store_owner_api_secrete — это точное публичное имя поля, включая его историческое написание. Это не токен Bearer. Поместите полную JSON-строку непосредственно в заголовок Authorization.

Храните секрет только в backend-коде. Не помещайте его в URL, browser bundle, публичный репозиторий, событие аналитики или лог приложения.

Есть ли официальные пакеты для Python и Node.js?

Да. Shoply публикует два серверных пакета, которые автоматически добавляют необходимую аутентификацию и предоставляют Merchant API в виде типизированных функций. Оба пакета имеют открытый исходный код в 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"

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

Пакет также предоставляет функции для аналитики, счетчиков активности, полных временных шкал сессий, часового пояса магазина и управления знаниями. См. его руководство по бизнес-сценариям использования  и справочник API .

Пакет 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 охватывает те же endpoint’ы Merchant API, что и пакет Python. См. его руководство по бизнес-сценариям использования  и справочник API .

Оба пакета предназначены для доверенных backend-сервисов, запланированных задач и приватных внутренних инструментов. Не импортируйте ни один из этих пакетов в storefront-код и не раскрывайте секрет API в browser bundle.

Можно ли вызывать HTTP API без пакета?

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

Установите Requests, если в вашей среде он еще не установлен:

python -m pip install requests

Хелпер ниже добавляет ключ магазина и заголовок аутентификации к каждому запросу:

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

Примеры ниже используют этот общий клиент. Оба хелпера автоматически добавляют аутентифицированный ключ магазина.

Можно ли управлять знаниями Shoply AI через API?

Да. admin_store_knowledge использует GET для получения знаний и POST для их создания, обновления, удаления или повторного обхода. POST, использующий существующий ID знания, обновляет эту запись; использование нового ID создает новую.

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

Запись знаний может изменить ответы, показываемые покупателям. Используйте отдельный секрет для системы, которая управляет знаниями, проверяйте содержимое перед отправкой и никогда не раскрывайте эти учетные данные с правом записи в JavaScript storefront’а.

Список существующих знаний

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

Создание или обновление пользовательского текстового знания

Выберите стабильный уникальный ID знания. При обновлении этой записи используйте тот же самый ID.

from time import time
 
knowledge_id = "knowledge::shipping-policy"
result = shoply_post(
    "admin_store_knowledge",
    {
        knowledge_id: {
            "title": "Shipping policy",
            "text": (
                "Orders leave our warehouse within two business days. "
                "Standard delivery normally takes three to five business days."
            ),
            "epoch_edit": int(time()),
        }
    },
)
 
print(result)

Пример ответа

{
  "statusCode": 200
}

Успешный ответ означает, что знание было сохранено. Индексация поиска может занять несколько минут, поэтому новый ответ может появиться не сразу. Если API сообщает, что содержимое сохранено, но индексация задерживается, подтвердите сохраненную запись через GET перед повторной попыткой записи.

Добавление внешней веб-страницы

Используйте ID, начинающийся с external_url::. Поместите полный URL http:// или https:// в text.

from time import time
 
result = shoply_post(
    "admin_store_knowledge",
    {
        "external_url::returns-policy": {
            "title": "Returns and exchanges",
            "text": "https://www.example.com/policies/returns",
            "epoch_edit": int(time()),
        }
    },
)

Загрузка и регистрация файла знаний

Файлы знаний должны быть в формате PDF, TXT или Markdown и быть меньше 5 МБ. Сначала загрузите файл, затем сохраните возвращенное приватное расположение S3 как запись знания.

from pathlib import Path
from time import time
 
file_path = Path("shipping-policy.md")
with file_path.open("rb") as file_handle:
    upload_response = session.post(
        f"{BASE_URL}/user_generated_file",
        params={"store_key": STORE_KEY, "folder": "knowledge_file"},
        files={"file": (file_path.name, file_handle, "text/markdown")},
        timeout=60,
    )
 
upload_response.raise_for_status()
uploaded = upload_response.json()
if uploaded.get("statusCode") != 200:
    raise RuntimeError(uploaded.get("error", "Knowledge file upload failed"))
 
shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_file::shipping-policy": {
            "title": "Shipping policy document",
            "text": uploaded["file_url"],
            "epoch_edit": int(time()),
        }
    },
)

Пример ответа на загрузку

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

Рассматривайте file_url как непрозрачное приватное расположение, возвращаемое Shoply. Не конструируйте и не изменяйте его самостоятельно.

Удаление знаний

Удаление необратимо. Сначала получите текущие записи и отправляйте только те точные ID, которые вы собираетесь удалить.

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

Запрос повторного обхода сайта

Используйте повторный обход после изменения контента на сайте продавца. Обычно он не требуется после каждого обновления пользовательского текста.

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

Бизнес-сценарии использования

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

Примеры Merchant API

1. Получение аналитики эффективности

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 ежедневную сводку о влиянии на продажи.
• Сравнивать поиски, клики по товарам, события добавления в корзину и покупки, чтобы найти потери на этапах воронки.
• Наполнять еженедельную или ежемесячную BI-панель без парсинга страницы 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.
• Обнаруживать необычные всплески трафика или резкие падения вовлеченности клиентов.
• Сравнивать объем поиска товаров с кликами, событиями добавления в корзину и checkout.
• Оценивать, когда командам поддержки и мерчандайзинга следует проверять самые загруженные периоды.

4. Получение сводок по сессиям чата и поиска

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.
• Выявлять сессии с высоким намерением покупки, содержащие поиски, клики по товарам или другие покупательские действия.
• Экспортировать одну строку на сессию для анализа трендов, избегая более крупного payload на уровне событий.

5. Получение одной полной сессии

Передайте выбранную сводку в query_log_visualization, чтобы получить события клиента, ИИ, поиска и 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": {}
    }
  ]
}

Временная шкала может содержать вопросы клиентов, ответы ИИ, результаты поиска, клики по товарам, события добавления в корзину, события checkout и участие живого агента. Используйте server_timestamp_ms для упорядочивания смешанных типов событий. Старые записи могут содержать меньше полей.

Бизнес-сценарии использования

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

Можно ли использовать один секрет для каждого API?

Да. Действительный store_owner_api_secrete привязан к одному магазину и работает со всеми endpoint’ами Merchant API, перечисленными выше. Для аккаунтов SiteChat этот же секрет также аутентифицирует API загрузки каталога. Для более безопасной работы используйте отдельные именованные секреты для разных систем — например, один для ночного экспорта данных и другой для внутренней панели.

Если одна интеграция будет выведена из эксплуатации или скомпрометирована, отзовите только ее секрет в настройках Shoply. Остальные интеграции продолжат работать.

Что нужно знать о сроке действия, конфиденциальности и ошибках?

Также ознакомьтесь с источниками данных и политикой конфиденциальности Shoply, чтобы понять, какая информация доступна для ответов клиентам.

• Секреты API владельца магазина истекают через 90 дней. Создайте замену и обновите интеграцию до даты истечения срока.
• Стандартный срок хранения истории чатов и поиска в Shoply также составляет 90 дней. Истечение срока действия секрета и хранение данных — это разные политики.
• Ответы истории могут содержать персональные данные, включая идентификаторы клиентов, адреса электронной почты, примерное местоположение, вопросы и покупательскую активность. Храните и обрабатывайте их в соответствии с вашей политикой конфиденциальности и применимым законодательством.
• HTTP 403 означает, что секрет отсутствует, недействителен, истек, отозван или принадлежит другому магазину.
• HTTP 422 обычно означает, что обязательный параметр запроса отсутствует или имеет неправильное имя.
• HTTP 500 или ответ с statusCode: 500 означает, что запрос достиг Shoply, но не смог быть завершен. Повторяйте временные сбои с backoff и свяжитесь с нами, если ошибка сохраняется.
• Используйте ограниченные диапазоны UTC для экспортов и регулярных задач, чтобы ответы оставались управляемыми.

Является ли поиск по товарам частью Merchant API?

Публичный API поиска товаров Shoply имеет другой контракт аутентификации и запросов. См. Как получить доступ к поиску Shoply AI через API, если вам нужны результаты поиска товаров для shopper-facing сценария, а не для приватных данных продавца.

Могут ли продавцы SiteChat загружать каталог товаров?

Да. Аккаунты SiteChat могут загружать структурированные товары и изображения товаров с тем же секретом API владельца магазина. Эти endpoint’ы каталога документированы отдельно в Как загрузить каталог для SiteChat. Магазины Shopify продолжают синхронизировать товары через Shopify и не используют эти маршруты загрузки.

Если вам нужна помощь с интеграцией, свяжитесь с Shoply AI.