Dokumentacja API

REST API dla wtyczki WooCommerce, integracji Shopify i dostępu do publicznych feedów.

Przegląd

API Sync2Sys to interfejs RESTful, który przyjmuje i zwraca dane w formacie JSON. Wszystkie żądania wykonywane są przez HTTPS.

Adres bazowy

https://panel.sync2sys.com/api

Typ treści

Każde żądanie powinno zawierać następujący nagłówek:

Content-Type: application/json

Limity zapytań (rate limiting)

Publiczne endpointy (np. opublikowane feedy) mają limit 30 żądań na minutę na adres IP. Endpointy z uwierzytelnianiem mają wyższe limity.

Uwierzytelnianie

Większość endpointów API wymaga ważnego tokenu JWT (JSON Web Token), przekazywanego jako token Bearer w nagłówku Authorization:

Authorization: Bearer <your_jwt_token>

Token JWT możesz uzyskać przez endpoint logowania lub w ramach automatycznego tworzenia konta przez wtyczkę WooCommerce.

Uwaga: Tokeny są wydawane podczas logowania i podłączania wtyczki. Przechowuj token w bezpiecznym miejscu, ponieważ identyfikuje on Twoje konto i organizację.

Endpointy wtyczki WooCommerce

Z tych endpointów korzysta wtyczka Sync2Sys dla WooCommerce do podłączania sklepów, zarządzania kontami i sprawdzania statusu synchronizacji.

POST /api/auth/register-from-plugin Publiczny

Automatyczna rejestracja konta w tle, inicjowana przez wtyczkę WooCommerce. Tworzy konto Sync2Sys (lub zwraca istniejące) i wydaje token JWT do kolejnych wywołań API.

Treść żądania

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

Odpowiedź 200

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

POST /api/stores/connect Publiczny

Podłącza sklep WooCommerce do Sync2Sys. Wtyczka przesyła dane dostępowe WooCommerce REST API, dzięki czemu Sync2Sys Cloud może zarządzać produktami przez WC REST API.

Treść żądania

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

Odpowiedź 200 / 201

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

Ważne: Pola consumerKey i consumerSecret to klucze WooCommerce REST API wygenerowane w sekcji WooCommerce → Ustawienia → Zaawansowane → REST API. Wymagają uprawnień do odczytu i zapisu.

POST /api/stores/disconnect 🔒 JWT

Odłącza sklep WooCommerce od Sync2Sys. Usuwa zapisane dane dostępowe API i dezaktywuje kanał sprzedaży.

Nagłówki

Authorization: Bearer <your_jwt_token>

Odpowiedź 200

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

GET /api/auth/account-status 🔒 JWT

Sprawdza bieżący status konta. Wtyczka WooCommerce używa tego endpointu, aby zweryfikować, czy połączenie jest aktywne, i wyświetlić informacje o planie.

Nagłówki

Authorization: Bearer <your_jwt_token>

Odpowiedź 200

{ "connected": true, "email": "admin@yourstore.com", "plan": "starter", "organizationName": "My Store" }

GET /api/sync/status 🔒 JWT

Zwraca bieżący status synchronizacji podłączonego sklepu: liczbę dostawców, liczbę feedów, liczbę zsynchronizowanych produktów oraz znacznik czasu ostatniej aktywności.

Nagłówki

Authorization: Bearer <your_jwt_token>

Odpowiedź 200

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

Shopify OAuth

Sklepy Shopify łączą się z Sync2Sys przez OAuth 2.0. Proces rozpoczyna się w panelu Sync2Sys.

POST /api/shopify/oauth/init 🔒 JWT

Rozpoczyna proces autoryzacji OAuth w Shopify. Zwraca adres URL, na który należy przekierować użytkownika do ekranu zgody Shopify.

Treść żądania

{ "shopDomain": "mystore.myshopify.com", "channelId": "uuid" // optional, to link to existing channel }

Odpowiedź 200

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

Wskazówka: Możesz przekazać samą nazwę sklepu (np. mystore), a API automatycznie doda .myshopify.com.

GET /api/shopify/oauth/callback Publiczny

Po autoryzacji Shopify przekierowuje użytkownika pod ten adres URL. Endpoint wymienia kod autoryzacyjny na token dostępu i tworzy lub aktualizuje kanał sprzedaży. Tego endpointu nie wywołujesz bezpośrednio, przekierowanie obsługuje Shopify.

Parametry zapytania

code — Authorization code from Shopify shop — Shop domain (e.g., mystore.myshopify.com) state — State parameter for CSRF validation hmac — HMAC signature for verification

Działanie

Po pomyślnej autoryzacji następuje przekierowanie na /sales-channels/:channelId?oauth=success. W przypadku błędu przekierowanie zawiera ?oauth=error&message=....

GET /api/shopify/oauth/status 🔒 JWT

Sprawdza, czy Shopify OAuth jest skonfigurowany na serwerze.

Odpowiedź 200

{ "configured": true }

Publiczne feedy

Opublikowane feedy eksportowe są dostępne pod publicznym adresem URL bez uwierzytelniania. Korzystają z nich zewnętrzne platformy, takie jak Google Shopping, Facebook Ads i porównywarki cen.

GET /api/public/feeds/:slug Publiczny

Pobiera opublikowany feed po jego slugu. Zwraca XML, CSV lub JSON, w zależności od skonfigurowanego formatu wyjściowego feedu.

Parametry URL

:slug — Feed slug (e.g., "google-shopping-feed")

Nagłówki odpowiedzi

Content-Type: application/xml; charset=utf-8 (or text/csv, application/json) Content-Disposition: inline; filename="google-shopping-feed.xml" Cache-Control: public, max-age=300 X-Feed-Products: 1247 X-Feed-Generated: 2024-03-15T14:30:00Z X-Cache: HIT (or MISS)

Treść odpowiedzi

Zawartość feedu w skonfigurowanym formacie (XML, CSV lub JSON).

Limit zapytań: 30 żądań na 60 sekund na adres IP. Odpowiedzi są buforowane na serwerze przez 5 minut.

Błędy

404 — Feed not found or not published 429 — Rate limit exceeded

Obsługa błędów

API używa standardowych kodów stanu HTTP, aby wskazać powodzenie lub niepowodzenie żądania.

Kody stanu

200 - OK: żądanie zakończone powodzeniem
201 - Created: zasób został utworzony
400 - Bad Request: nieprawidłowe lub brakujące parametry
401 - Unauthorized: brak tokenu JWT lub token nieprawidłowy
403 - Forbidden: niewystarczające uprawnienia lub osiągnięty limit planu
404 - Not Found: zasób nie istnieje
429 - Too Many Requests: przekroczony limit zapytań
500 - Internal Server Error: wewnętrzny błąd serwera

Format odpowiedzi błędu

{ "statusCode": 400, "message": "Description of what went wrong", "error": "Bad Request" }

Niektóre endpointy mogą zwracać w odpowiedzi błędu dodatkowe pola (np. error: "PIM_PRODUCT_LIMIT"), które umożliwiają bardziej precyzyjną obsługę błędów.