API dokumentacija

Apžvalga

Sync2Sys API yra RESTful API, kuri priima ir grąžina JSON. Visos užklausos siunčiamos per HTTPS.

Bazinis URL

https://panel.sync2sys.com/api

Turinio tipas

Visos užklausos turėtų turėti šią antraštę:

Content-Type: application/json

Užklausų limitas

Viešos prieigos taškai (pvz., publikuoti srautai) ribojami iki 30 užklausų per minutę vienam IP adresui. Autentifikuoti taškai turi aukštesnius limitus.

Autentifikavimas

Daugumai API prieigos taškų reikalingas galiojantis JWT (JSON Web Token), perduodamas kaip Bearer žetonas Authorization antraštėje:

Authorization: Bearer <jusu_jwt_zetonas>

JWT žetoną galite gauti per prisijungimo tašką arba per WooCommerce papildinio automatinę paskyros kūrimo seką.

Pastaba: Žetonai išduodami prisijungimo ir papildinio prijungimo metu. Saugokite žetoną saugiai — jis identifikuoja jūsų paskyrą ir organizaciją.

WooCommerce papildinio prieigos taškai

Šiuos prieigos taškus naudoja Sync2Sys WooCommerce papildinys parduotuvėms prijungti, paskyroms valdyti ir sinchronizacijos būsenai tikrinti.

POST /api/auth/register-from-plugin Viešas

Tylus paskyros sukūrimas, inicijuotas WooCommerce papildinio. Sukuria Sync2Sys paskyrą (arba grąžina esamą) ir pateikia JWT žetoną tolesniams API iškvietimams.

Užklausos kūnas

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

Atsakymas 200

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

POST /api/stores/connect Viešas

Prijungti WooCommerce parduotuvę prie Sync2Sys. Papildinys siunčia WooCommerce REST API prisijungimo duomenis, kad Sync2Sys galėtų valdyti produktus per WC REST API.

Užklausos kūnas

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

Atsakymas 200 / 201

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

Svarbu: consumerKey ir consumerSecret yra WooCommerce REST API raktai, sugeneruoti per WooCommerce → Nustatymai → Išplėstiniai → REST API. Jiems reikalinga skaitymo/rašymo prieiga.

POST /api/stores/disconnect 🔒 JWT

Atjungti WooCommerce parduotuvę nuo Sync2Sys. Pašalina saugomus API prisijungimo duomenis ir deaktyvuoja pardavimo kanalą.

Antraštės

Authorization: Bearer <jusu_jwt_zetonas>

Atsakymas 200

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

GET /api/auth/account-status 🔒 JWT

Patikrinti esamą paskyros būseną. Naudojama WooCommerce papildinyje prisijungimo aktyvumui patikrinti ir plano informacijai rodyti.

Antraštės

Authorization: Bearer <jusu_jwt_zetonas>

Atsakymas 200

{ "connected": true, "email": "admin@jusuparduotuve.com", "plan": "starter", "organizationName": "Mano parduotuvė" }

GET /api/sync/status 🔒 JWT

Gauti esamą sinchronizacijos būseną prijungtai parduotuvei. Rodo tiekėjų, srautų skaičių, sinchronizuotų produktų kiekį ir paskutinės veiklos laiką.

Antraštės

Authorization: Bearer <jusu_jwt_zetonas>

Atsakymas 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 parduotuvės jungiasi prie Sync2Sys per OAuth 2.0. Procesas inicijuojamas iš Sync2Sys panelės.

POST /api/shopify/oauth/init 🔒 JWT

Pradėti Shopify OAuth autorizacijos seką. Grąžina URL nukreipimui į Shopify sutikimo puslapį.

Užklausos kūnas

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

Atsakymas 200

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

GET /api/shopify/oauth/callback Viešas

Shopify nukreipia naudotoją į šį URL po autorizacijos. Šis taškas apsikeičia autorizacijos kodu į prieigos žetoną. Šio tiesiogiai nekviečiate — Shopify apdoroja nukreipimą.

Užklausos parametrai

code — Autorizacijos kodas iš Shopify shop — Parduotuvės domenas state — Būsenos parametras CSRF validacijai hmac — HMAC parašas patvirtinimui

GET /api/shopify/oauth/status 🔒 JWT

Patikrinti, ar Shopify OAuth sukonfigūruotas serveryje.

Atsakymas 200

{ "configured": true }

Vieši srautai

Publikuoti eksporto srautai pasiekiami viešu URL be autentifikacijos. Šie srautai naudojami trečiųjų šalių platformose kaip Google Shopping, Facebook Ads ir kainų palyginimo svetainėse.

GET /api/public/feeds/:slug Viešas

Gauti publikuotą srautą pagal jo slug. Grąžina XML, CSV arba JSON priklausomai nuo srauto sukonfigūruoto formato.

URL parametrai

:slug — Srauto slug (pvz., "google-shopping-feed")

Atsakymo antraštės

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

Limitas: 30 užklausų per 60 sekundžių vienam IP adresui. Atsakymai kešuojami 5 minutes.

Klaidos

404 — Srautas nerastas arba nepublikuotas 429 — Viršytas užklausų limitas

Klaidų apdorojimas

API naudoja standartinius HTTP būsenos kodus užklausos sėkmei ar nesėkmei nurodyti.

Būsenos kodai

200 — Gerai, užklausa sėkminga
201 — Sukurta, resursas sėkmingai sukurtas
400 — Bloga užklausa, neteisingi arba trūkstami parametrai
401 — Neautorizuota, trūksta ar neteisingas JWT žetonas
403 — Draudžiama, nepakankamos teisės arba plano limitai viršyti
404 — Nerasta, resursas neegzistuoja
429 — Per daug užklausų, limitas viršytas
500 — Vidinė serverio klaida

Klaidos atsakymo formatas

{ "statusCode": 400, "message": "Klaidos aprašymas", "error": "Bad Request" }