API документация

Обзор

Sync2Sys API — это RESTful API, которое принимает и возвращает JSON. Все запросы выполняются через HTTPS.

Базовый URL

https://panel.sync2sys.com/api

Тип контента

Все запросы должны включать следующий заголовок:

Content-Type: application/json

Ограничение запросов

Публичные точки доступа (например, опубликованные фиды) ограничены до 30 запросов в минуту с одного IP-адреса. Аутентифицированные точки имеют более высокие лимиты.

Аутентификация

Для большинства API точек требуется действительный JWT (JSON Web Token), передаваемый как Bearer токен в заголовке Authorization:

Authorization: Bearer <vash_jwt_token>

JWT токен можно получить через точку входа или через автоматическое создание аккаунта плагином WooCommerce.

Примечание: Токены выдаются при входе и подключении плагина. Храните токен в безопасности — он идентифицирует ваш аккаунт и организацию.

Точки доступа плагина WooCommerce

Эти точки доступа используются плагином Sync2Sys WooCommerce для подключения магазинов, управления аккаунтами и проверки статуса синхронизации.

POST /api/auth/register-from-plugin Публичный

Тихое создание аккаунта, инициированное плагином WooCommerce. Создаёт аккаунт Sync2Sys (или возвращает существующий) и предоставляет JWT токен для последующих API вызовов.

Тело запроса

{ "email": "admin@vashmagazin.com", "storeUrl": "https://vashmagazin.com", "source": "woo-plugin" }

Ответ 200

{ "token": "eyJhbGciOiJIUzI1...", "user": { "id": "uuid", "email": "admin@vashmagazin.com" }, "isNewAccount": true }

POST /api/stores/connect Публичный

Подключить магазин WooCommerce к Sync2Sys. Плагин отправляет учётные данные WooCommerce REST API, чтобы Sync2Sys мог управлять товарами через WC REST API.

Тело запроса

{ "storeUrl": "https://vashmagazin.com", "consumerKey": "ck_xxxxxxxxxxxxxxxxxxxxxxxx", "consumerSecret": "cs_xxxxxxxxxxxxxxxxxxxxxxxx", "email": "admin@vashmagazin.com", "platform": "woocommerce", "pluginVersion": "1.1.0" }

Ответ 200 / 201

{ "success": true, "token": "eyJhbGciOiJIUzI1...", "channelId": "uuid", "message": "Store connected successfully" }

Важно: consumerKey и consumerSecret — это ключи WooCommerce REST API, сгенерированные через WooCommerce → Настройки → Расширенные → REST API. Они требуют доступ на чтение/запись.

POST /api/stores/disconnect 🔒 JWT

Отключить магазин WooCommerce от Sync2Sys. Удаляет сохранённые учётные данные API и деактивирует канал продаж.

Заголовки

Authorization: Bearer <vash_jwt_token>

Ответ 200

{ "success": true, "message": "Store disconnected" }

GET /api/auth/account-status 🔒 JWT

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

Заголовки

Authorization: Bearer <vash_jwt_token>

Ответ 200

{ "connected": true, "email": "admin@vashmagazin.com", "plan": "starter", "organizationName": "Мой магазин" }

GET /api/sync/status 🔒 JWT

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

Заголовки

Authorization: Bearer <vash_jwt_token>

Ответ 200

{ "suppliers": 3, "feeds": 5, "products_synced": 1247, "last_sync": "2024-03-15T14:30:00Z", "last_activity": "2024-03-15T15:00:00Z" }

Shopify OAuth

Магазины Shopify подключаются к Sync2Sys через OAuth 2.0. Процесс инициируется из панели Sync2Sys.

POST /api/shopify/oauth/init 🔒 JWT

Начать последовательность авторизации Shopify OAuth. Возвращает URL для перенаправления на страницу согласия Shopify.

Тело запроса

{ "shopDomain": "moiMagazin.myshopify.com", "channelId": "uuid" }

Ответ 200

{ "authUrl": "https://moiMagazin.myshopify.com/admin/oauth/authorize?..." }

GET /api/shopify/oauth/callback Публичный

Shopify перенаправляет пользователя на этот URL после авторизации. Эта точка обменивает код авторизации на токен доступа. Вы не вызываете это напрямую — Shopify обрабатывает перенаправление.

Параметры запроса

code — Код авторизации от Shopify shop — Домен магазина state — Параметр состояния для CSRF валидации hmac — Подпись HMAC для верификации

GET /api/shopify/oauth/status 🔒 JWT

Проверить, настроен ли Shopify OAuth на сервере.

Ответ 200

{ "configured": true }

Публичные фиды

Опубликованные экспортные фиды доступны по публичному URL без аутентификации. Эти фиды используются сторонними платформами, такими как Google Shopping, Facebook Ads и сайтами сравнения цен.

GET /api/public/feeds/:slug Публичный

Получить опубликованный фид по его slug. Возвращает XML, CSV или JSON в зависимости от настроенного формата фида.

Параметры URL

:slug — Slug фида (напр., "google-shopping-feed")

Заголовки ответа

Content-Type: application/xml; charset=utf-8 Cache-Control: public, max-age=300 X-Feed-Products: 1247 X-Feed-Generated: 2024-03-15T14:30:00Z

Ограничение: 30 запросов за 60 секунд с одного IP-адреса. Ответы кэшируются на 5 минут.

Ошибки

404 — Фид не найден или не опубликован 429 — Превышен лимит запросов

Обработка ошибок

API использует стандартные HTTP коды статуса для указания успеха или неудачи запроса.

Коды статуса

200 — Хорошо, запрос успешен
201 — Создано, ресурс успешно создан
400 — Плохой запрос, недопустимые или отсутствующие параметры
401 — Неавторизован, отсутствует или недействителен JWT токен
403 — Запрещено, недостаточно прав или превышены лимиты плана
404 — Не найдено, ресурс не существует
429 — Слишком много запросов, лимит превышен
500 — Внутренняя ошибка сервера

Формат ответа об ошибке

{ "statusCode": 400, "message": "Описание ошибки", "error": "Bad Request" }