API sklepu

Ta dokumentacja opisuje aktualny zakres API instancji sklepu. Sklep posiada publiczne API integracyjne dla zewnetrznych systemow oraz osobne, wewnetrzne API panelu administracyjnego.

Base URL

Domyslna baza API:

https://twoj-sklep.syls.eu/api/v1

Publiczne endpointy integracyjne pluginu Shop sa pod:

/api/v1/shop

Endpointy panelowe sa pod /api/v1/shop/admin i nie sa przeznaczone do integracji zewnetrznych.

Charakter API

API jest podzielone na dwa zastosowania:

  • /shop - publiczne API dla integracji zewnetrznych, zabezpieczone osobnymi tokenami sklepu i zakresami uprawnien;
  • /shop/admin - API panelu sprzedawcy i pracownikow, uzywane przez interfejs sklepu po zalogowaniu.

Autoryzacja

Publiczne API:

Authorization: Bearer ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token mozna tez przekazac naglowkiem:

X-Shop-API-Token: ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokeny tworzy sie per integracja:

php bin/shop-api-token list
php bin/shop-api-token create --name="ERP" --scopes=products:read,orders:read,customers:read
php bin/shop-api-token revoke --id=erp

Dostepne zakresy:

  • products:read;
  • products:write;
  • orders:read;
  • orders:write;
  • customers:read.

API panelowe uzywa sesji SYLS Admin albo tokenu API panelu SYLS, jezeli dana instalacja ma go wlaczony.

Format odpowiedzi

Odpowiedzi sa JSON. Typowy sukces zwraca dane w obiekcie:

{
  "data": {
    "status": "ok"
  }
}

Bledy nalezy obslugiwac po statusie HTTP oraz polach message, detail albo title, zaleznie od warstwy, ktora zwrocila blad.

Kontrakt OpenAPI dla publicznego API jest dostepny jako plik:

/api/v1/platform/openapi/shop

Stan panelu

GET /shop/admin/state

Zwraca stan startowy panelu sklepu:

  • aktywny pakiet i capabilities;
  • uprawnienia zalogowanego uzytkownika;
  • zespol;
  • ustawienia;
  • operacje;
  • compliance;
  • demo;
  • transfery;
  • slowniki i metadane UI.

GET /shop/admin/dashboard

Zwraca dane dashboardu:

  • liczby zamowien;
  • statusy platnosci i realizacji;
  • produkty z niskim stanem;
  • zadania personalizacji;
  • opinie;
  • podstawowe wskazniki sprzedazy.

Produkty

GET /shop/admin/products

Zwraca produkty do grida panelu. Dane obejmuja m.in. trase, tytul, SKU, widocznosc, aktywnosc sprzedazy, stan, warianty, typ produktu i partnera realizacyjnego.

Przykladowe zastosowania:

  • lista produktow w panelu;
  • filtrowanie katalogu;
  • szybka kontrola stanow;
  • przygotowanie eksportu operacyjnego.

PATCH /shop/admin/products

Aktualizuje pojedynczy produkt z grida.

Typowe pola:

{
  "route": "/produkty/kubki/klasyczne/kubek-0011",
  "enabled": true,
  "visible": true,
  "stock": 24,
  "low_stock_threshold": 5
}

PATCH /shop/admin/products/batch

Masowa aktualizacja produktow. Uzywane do publikacji, ukrywania, wlaczania lub wylaczania sprzedazy oraz zapisu zmian w widoku produktow.

Magazyn

GET /shop/admin/inventory/state

Zwraca stan magazynowy produktu lub wariantu.

Parametry:

  • route;
  • sku.

POST /shop/admin/inventory/adjust

Zmienia stan produktu lub wariantu. Operacja powinna miec powod albo notatke. Zmiana zapisuje ruch magazynowy i audit log.

Zamowienia

GET /shop/admin/orders/{orderId}

Zwraca szczegol zamowienia:

  • klient;
  • adres rozliczeniowy i dostawy;
  • pozycje;
  • platnosc;
  • dostawa;
  • dokumenty;
  • fulfillment;
  • personalizacja;
  • historia;
  • tracking;
  • dostepne akcje workflow.

POST /shop/admin/orders/{orderId}/actions/{action}

Uruchamia akcje workflow zamowienia. Dostepne akcje zaleza od statusu i uprawnien. Przyklady:

  • oznaczenie jako w realizacji;
  • oznaczenie jako wyslane;
  • oznaczenie jako zakonczone;
  • anulowanie;
  • oznaczenie platnosci.

POST /shop/admin/orders/{orderId}/tracking

Zapisuje tracking zamowienia.

Przykladowe pola:

{
  "tracking_number": "123456789",
  "tracking_url": "https://tracking.example/123456789",
  "carrier": "Kurier",
  "notify_customer": true,
  "mark_shipped": true
}

GET /shop/admin/orders/{orderId}/invoice/{token}

Pobiera fakture PDF z prywatnego storage.

GET /shop/admin/orders/{orderId}/order-pdf

Generuje albo pobiera PDF zamowienia.

GET /shop/admin/orders/{orderId}/wz-pdf

Generuje albo pobiera dokument WZ.

GET /shop/admin/orders/{orderId}/personalization-files/{token}

Pobiera prywatny plik personalizacji przypisany do zamowienia.

POST /shop/admin/orders/{orderId}/items/{itemIndex}/personalization-approval

Wysyla projekt do akceptacji klienta albo zapisuje kolejna wersje projektu. Dotyczy procesow personalizacji w pakiecie PRO.

Fulfillment PRO

Endpointy fulfillmentu sluza do obslugi realizacji dzielonych miedzy partnerow.

POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/status
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/notes
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/tracking
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/issue
POST /shop/admin/orders/{orderId}/fulfillments/{fulfillmentId}/notify

Typowe statusy realizacji:

  • oczekuje;
  • w toku;
  • problem;
  • zakonczone.

Portal partnera PRO

Partner realizacyjny widzi tylko przypisane realizacje i potrzebne pliki.

GET  /shop/admin/partner/fulfillments
POST /shop/admin/partner/fulfillments/{fulfillmentId}/status
POST /shop/admin/partner/fulfillments/{fulfillmentId}/tracking
POST /shop/admin/partner/fulfillments/{fulfillmentId}/issue
GET  /shop/admin/partner/fulfillments/{fulfillmentId}/personalization-files/{token}
POST /shop/admin/partner/fulfillments/{fulfillmentId}/items/{itemIndex}/personalization-approval

Zespol i 2FA

POST   /shop/admin/team
PATCH  /shop/admin/team/{username}
DELETE /shop/admin/team/{username}
PATCH  /shop/admin/security
POST   /shop/admin/security/current-user/setup
POST   /shop/admin/security/current-user/confirm
POST   /shop/admin/security/current-user/disable

Zastosowania:

  • tworzenie kont pracownikow;
  • aktualizacja roli i uprawnien;
  • usuwanie albo dezaktywacja pracownika;
  • wlaczanie i wymuszanie 2FA;
  • konfiguracja 2FA dla aktualnego uzytkownika.

Ustawienia

PATCH /shop/admin/settings

Zapisuje ustawienia sklepu:

  • wyglad i publiczna czesc sklepu;
  • homepage;
  • kanaly i trasy;
  • tresci stron i e-maili;
  • dostawy;
  • platnosci;
  • walute;
  • faktury;
  • SEO, sitemap i merchant feed;
  • analytics i cookie consent;
  • typy produktow;
  • producenci;
  • partnerzy realizacyjni w PRO;
  • bezpieczne ustawienia wydajnosci.

Uploady

POST /shop/admin/settings/logo
POST /shop/admin/settings/favicon
POST /shop/admin/settings/theme-image
POST /shop/admin/settings/manufacturer-logo

Uploady sa przeznaczone dla panelu. Zewnetrzne integracje nie powinny ich uzywac bez osobnego kontraktu.

Compliance

GET /shop/admin/compliance/state

Zwraca checklisty i statusy:

  • SEO;
  • sitemap;
  • schema.org;
  • etykiety formularzy;
  • ARIA i dostepnosc;
  • analityka;
  • cookies;
  • rate limiting;
  • audit log.

Operacje ROZWÓJ

GET  /shop/admin/operations/state
GET  /shop/admin/operations/report
POST /shop/admin/operations/orders-export
POST /shop/admin/operations/fulfillments-export
POST /shop/admin/operations/data-export
GET  /shop/admin/operations/download/{token}

Filtry raportu:

  • from, to;
  • status;
  • payment_status;
  • fulfillment_status;
  • channel;
  • q.

Eksporty moga obejmowac zamowienia, realizacje albo paczke danych sklepu.

Demo

GET  /shop/admin/demo/state
POST /shop/admin/demo/install
POST /shop/admin/demo/clear

Instalacja demo dodaje przykladowe dane. Czyszczenie demo nie powinno usuwac kont, sekretow, ustawien platnosci, konfiguracji Mail ani realnych zamowien.

Kanaly i jezyki

POST   /shop/admin/channels
DELETE /shop/admin/channels/{channelCode}

Kanal jezykowy moze miec osobne trasy, walute, tresci stron i teksty e-maili. Usuniecie kanalu jest blokowane, jezeli istnieja produkty albo dane zalezne.

Transfer produktow ROZWÓJ

POST /shop/admin/transfers/template
POST /shop/admin/transfers/export
POST /shop/admin/transfers/upload
POST /shop/admin/transfers/preview
POST /shop/admin/transfers/import
GET  /shop/admin/transfers/{jobId}/download/{token}

Proces importu:

  1. Pobierz szablon.
  2. Uzupelnij produkty i media.
  3. Wgraj plik.
  4. Uruchom preview.
  5. Popraw bledy walidacji.
  6. Dopiero potem wykonaj import.

Publiczne feedy

To nie sa endpointy /api/v1, ale sa wazne dla integracji:

/sitemap.xml
/sitemap-{channel}.xml
/merchant.xml
/merchant-{channel}.xml

Sitemap sluzy wyszukiwarkom. Merchant feed jest przeznaczony dla katalogow produktowych i reklam.

Publiczne API do integracji

Publiczne API jest osobnym kontraktem dla zewnetrznych integracji. Jest niezalezne od API panelu i korzysta z tokenow per sklep/per integracja.

Kazde wywolanie publiczne:

  • wymaga tokenu Authorization: Bearer ...;
  • sprawdza scope;
  • przechodzi przez rate limiting;
  • zapisuje wpis audytu;
  • zwraca tylko dane potrzebne integracji, bez tokenow dokumentow i danych panelowych.

Products

GET /api/v1/shop/products
GET /api/v1/shop/products/{sku}
PATCH /api/v1/shop/products/{sku}
GET /api/v1/shop/products/{sku}/inventory
PATCH /api/v1/shop/products/{sku}/inventory

Wymagane scope'y:

  • odczyt: products:read;
  • zapis: products:write.

Zastosowania:

  • synchronizacja ERP;
  • aktualizacja stanow magazynowych;
  • pobieranie katalogu;
  • wlaczanie/wylaczanie sprzedazy;
  • publikacja/ukrywanie produktow.

Orders

GET /api/v1/shop/orders
GET /api/v1/shop/orders/{id}
PATCH /api/v1/shop/orders/{id}/status
PATCH /api/v1/shop/orders/{id}/tracking

Wymagane scope'y:

  • odczyt: orders:read;
  • zapis statusu i trackingu: orders:write.

Zastosowania:

  • pobieranie nowych zamowien do systemu magazynowego;
  • aktualizacja statusu realizacji;
  • wysylka numeru trackingowego;
  • synchronizacja referencji platnosci.

Customers

GET /api/v1/shop/customers
GET /api/v1/shop/customers/{id}
GET /api/v1/shop/customers/{id}/orders

Wymagane scope'y:

  • dane klientow: customers:read;
  • zamowienia klienta: orders:read.

Zastosowania:

  • raportowanie klientow;
  • integracje CRM;
  • historia zakupow.

Webhooki outbound

Webhooki wychodzace nie sa jeszcze czescia podstawowego publicznego API. To bedzie osobny modul integracyjny, wlaczany wtedy, gdy klient potrzebuje powiadomien push zamiast okresowego pobierania danych.

Przykladowe przyszle zdarzenia:

  • order.created;
  • order.paid;
  • order.shipped;
  • order.canceled;
  • fulfillment.issue;
  • review.created;
  • product.low_stock.

Zasady bezpiecznego dostepu

Publiczny dostep do API powinien byc wlaczany tylko dla konkretnych integracji. Standard bezpieczenstwa obejmuje:

  • osobny token dla kazdej integracji;
  • ograniczone zakresy uprawnien, np. tylko odczyt zamowien albo tylko stany magazynowe;
  • limity zapytan, zeby zewnetrzny system nie przeciazyl sklepu;
  • log audytu pokazujacy kto i kiedy uzyl API;
  • kontrakt /api/v1 i dokument OpenAPI dla programisty integracji;
  • mozliwosc rotacji albo uniewaznienia tokenu bez wplywu na panel sklepu;
  • minimalny zakres danych osobowych przekazywany do zewnetrznego systemu.

Jezeli sklep potrzebuje integracji z ERP, magazynem, CRM albo marketplace, najbezpieczniej zaczac od ustalenia, ktore dane maja byc odczytywane, ktore zapisywane i czy integracja ma dzialac jednokierunkowo czy dwukierunkowo.