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

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

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

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

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

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

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

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

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

Как создать 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.

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

Существуют ли официальные пакеты для Python и Node.js?

Да. Shoply публикует два серверных пакета, которые автоматически добавляют требуемую аутентификацию и предоставляют Merchant API в виде типизированных функций. Оба пакета имеют открытый исходный код и размещены в организации shoplyai-public на GitHub.

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

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

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

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

Установите 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 витрины.

Просмотр существующих знаний

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.
• Добавляйте страницу с правилами или утверждённый документ в базу знаний в рамках процесса развёртывания.
• Удаляйте устаревшие сведения сразу после окончания действия правила или акции.

Примеры Merchant API

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

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

Конечная точка

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.

Бизнес-сценарии

• Отправляйте продавцу или команде электронной коммерции ежедневную сводку влияния на продажи.
• Сравнивайте поисковые запросы, клики по товарам, добавления в корзину и покупки, чтобы находить потери на этапах воронки.
• Наполняйте еженедельную или ежемесячную панель бизнес-аналитики без извлечения данных со страницы Shoply Admin.
• Отслеживайте связанную выручку во времени и сопоставляйте её с изменениями мерчандайзинга или кампаний.

2. Получение часового пояса магазина

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

Конечная точка

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.

Конечная точка

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

Строки содержат доступные за этот период счётчики активности, например вопросы в чате, поисковые запросы, клики, добавления в корзину и события оформления заказа. Счётчики без активности могут отсутствовать, а не иметь значение ноль.

Бизнес-сценарии

• Создавайте почасовой или ежедневный график активности, аналогичный графику в Chat & Search History.
• Обнаруживайте необычные всплески трафика или внезапное снижение вовлечённости клиентов.
• Сравнивайте объём поиска товаров с кликами, добавлениями в корзину и оформлениями заказа.
• Определяйте, когда командам поддержки и мерчандайзинга следует изучить самые загруженные периоды.

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

query_sessionized_chat возвращает одну компактную запись для каждой сессии клиента. Она также заполняет список сессий в Analytics → Chat & Search History.

Конечная точка

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

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

Передайте выбранную сводку в query_log_visualization, чтобы получить события клиента, AI, поиска и покупок.

Конечная точка

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

Бизнес-сценарии

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

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

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

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

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

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

Входит ли поиск товаров в Merchant API?

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

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