Dokumentacja API

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

Przegląd

Interfejs API Sync2Sys to interfejs API RESTful, który akceptuje i zwraca kod JSON. Wszystkie żądania są wysyłane za pośrednictwem protokołu HTTPS.

Bazowy adres URL

https://panel.sync2sys.com/api

Typ zawartości

Wszystkie żądania powinny zawierać następujący nagłówek:

Typ zawartości: aplikacja/json

Ograniczanie szybkości

Publiczne punkty końcowe (np. opublikowane kanały) są ograniczone do 30 żądań na minutę na adres IP. Uwierzytelnione punkty końcowe mają wyższe limity.

Uwierzytelnianie

Większość punktów końcowych interfejsu API wymaga prawidłowego tokenu JWT (token sieciowy JSON) przekazywanego jako token nośnika w pliku Upoważnienie chodnikowiec:

Autoryzacja: Nosiciel <your_jwt_token>

Możesz uzyskać token JWT za pośrednictwem punktu końcowego logowania lub poprzez automatyczny proces tworzenia konta wtyczki WooCommerce.

Notatka: Tokeny wydawane są podczas logowania i połączenia wtyczki. Przechowuj token w bezpieczny sposób — identyfikuje on Twoje konto i organizację.

Punkty końcowe wtyczki WooCommerce

Te punkty końcowe są używane przez Wtyczka Sync2Sys WooCommerce aby łączyć sklepy, zarządzać kontami i sprawdzać status synchronizacji.

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

Cicha rejestracja konta inicjowana przez wtyczkę WooCommerce. Tworzy konto Sync2Sys (lub zwraca istniejące) i udostępnia token JWT dla 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

Połącz sklep WooCommerce z Sync2Sys. Wtyczka wysyła dane uwierzytelniające WooCommerce REST API, dzięki czemu Sync2Sys Cloud może zarządzać produktami poprzez 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żny: The klucz konsumenta I tajemnica konsumenta to klucze WooCommerce REST API wygenerowane z WooCommerce → Ustawienia → Zaawansowane → API REST. Wymagają dostępu do odczytu/zapisu.

POST /api/stores/disconnect 🔒JWT

Odłącz sklep WooCommerce od Sync2Sys. Usuwa zapisane dane uwierzytelniające API i dezaktywuje kanał sprzedaży.

Nagłówki

Autoryzacja: Nosiciel <your_jwt_token>

Odpowiedź 200

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

DOSTAWAĆ /api/auth/status konta 🔒JWT

Sprawdź aktualny stan konta. Używany przez wtyczkę WooCommerce do sprawdzania, czy połączenie jest aktywne i wyświetlania informacji o planie.

Nagłówki

Autoryzacja: Nosiciel <your_jwt_token>

Odpowiedź 200

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

DOSTAWAĆ /api/sync/status 🔒JWT

Uzyskaj aktualny stan synchronizacji dla połączonego sklepu. Pokazuje liczbę dostawców, liczbę kanałów, zsynchronizowane produkty i sygnaturę czasową ostatniej aktywności.

Nagłówki

Autoryzacja: Nosiciel <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 poprzez OAuth 2.0. Przepływ jest inicjowany z panelu Sync2Sys.

POST /api/shopify/oauth/init 🔒JWT

Rozpocznij proces autoryzacji Shopify OAuth. Zwraca adres URL, który przekieruje 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. mój sklep) — interfejs API zostanie automatycznie dodany .myshopify.com.

DOSTAWAĆ /api/shopify/oauth/callback Publiczny

Shopify przekierowuje użytkownika na ten adres URL po autoryzacji. Ten punkt końcowy wymienia kod autoryzacyjny na token dostępu i tworzy/aktualizuje kanał sprzedaży. Nie nazywasz tego bezpośrednio — Shopify obsługuje przekierowanie.

Parametry zapytania

code — Kod autoryzacyjny od Shopify sklep — domena sklepu (np. mystore.myshopify.com) stan — Parametr stanu do sprawdzania poprawności CSRF hmac — podpis HMAC do weryfikacji

Zachowanie

Jeśli się powiedzie, przekierowuje do /sales-channels/:channelId?oauth=success. W przypadku błędu przekierowuje za pomocą ?oauth=błąd&wiadomość=....

DOSTAWAĆ /api/shopify/oauth/status 🔒JWT

Sprawdź, czy na serwerze skonfigurowano Shopify OAuth.

Odpowiedź 200

{ "configured": true }

Kanały publiczne

Opublikowane kanały eksportu są dostępne za pośrednictwem publicznego adresu URL bez uwierzytelniania. Te kanały są wykorzystywane przez platformy zewnętrzne, takie jak Zakupy Google, reklamy na Facebooku i porównywarki cen.

DOSTAWAĆ /api/public/feeds/:slug Publiczny

Pobierz opublikowany kanał za pomocą ślimaka. Zwraca XML, CSV lub JSON w zależności od skonfigurowanego formatu wyjściowego pliku danych.

Parametry adresu URL

:slug — ślimak paszowy (np. „google-shopping-feed”)

Nagłówki odpowiedzi

Typ zawartości: aplikacja/xml; charset=utf-8 (lub tekst/csv, aplikacja/json) Dyspozycja treści: inline; nazwa pliku="google-shopping-feed.xml" Kontrola pamięci podręcznej: publiczna, maksymalny wiek = 300 Produkty X-Feed: 1247 Wygenerowano X-Feed: 2024-03-15T14:30:00Z X-Cache: HIT (lub MISS)

Treść odpowiedzi

Zawartość kanału w skonfigurowanym formacie (XML, CSV lub JSON).

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

Błędy

404 — Kanał nie został znaleziony lub nieopublikowany 429 — Przekroczono limit szybkości

Obsługa błędów

Interfejs API wykorzystuje standardowe kody stanu HTTP do wskazania powodzenia lub niepowodzenia żądania.

Kody stanu

200 — OK, żądanie powiodło się
201 — Utworzono, zasób został pomyślnie utworzony
400 — Złe żądanie, nieprawidłowe lub brakujące parametry
401 — Nieautoryzowany, brakujący lub nieprawidłowy token JWT
403 — Zabronione, osiągnięto niewystarczające uprawnienia lub limity planu
404 — Nie znaleziono, zasób nie istnieje
429 — Zbyt wiele żądań, przekroczono limit szybkości
500 — Wewnętrzny błąd serwera

Format odpowiedzi na błąd

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

Niektóre punkty końcowe mogą zwracać dodatkowe pola w odpowiedzi na błąd (np. błąd: „PIM_PRODUCT_LIMIT”) w celu bardziej szczegółowej obsługi błędów.