API sklepu

Ta dokumentacja opisuje aktualny zakres API instancji sklepu. Sklep posiada publiczne API integracyjne dla zewnętrznych systemów oraz osobne, wewnętrzne API panelu administracyjnego.

Base URL

Domyślna baza API:

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

Publiczne endpointy integracyjne pluginu Shop są pod:

/api/v1/shop

Endpointy panelowe są pod /api/v1/shop/admin i nie są przeznaczone do integracji zewnętrznych.

Charakter API

API jest podzielone na dwa zastosowania:

  • /shop - publiczne API dla integracji zewnętrznych, zabezpieczone osobnymi tokenami sklepu i zakresami uprawnień;
  • /shop/admin - API panelu sprzedawcy i pracowników, używane przez interfejs sklepu po zalogowaniu.

Autoryzacja

Publiczne API:

Authorization: Bearer ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token można tez przekazać nagłówkiem:

X-Shop-API-Token: ks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokeny tworzy się 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

Dostępne zakresy:

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

API panelowe używa sesji SYLS Admin albo tokenu API panelu SYLS, jeżeli dana instalacja ma go włączony.

Format odpowiedzi

Odpowiedzi są JSON. Typowy sukces zwraca dane w obiekcie:

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

Błędy należy obsługiwać po statusie HTTP oraz polach message, detail albo title, zależnie od warstwy, która zwróciła błąd.

Kontrakt OpenAPI dla publicznego API jest dostępny jako plik:

/api/v1/platform/openapi/shop

Publiczne API do integracji

Publiczne API jest osobnym kontraktem dla zewnętrznych integracji. Jest niezależne od API panelu i korzysta z tokenów per sklep/per integracja.

Każde wywołanie publiczne:

  • wymaga tokenu Authorization: Bearer ...;
  • sprawdza scope;
  • przechodzi przez rate limiting;
  • zapisuje wpis audytu;
  • zwraca tylko dane potrzebne integracji, bez tokenów dokumentów 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 stanów magazynowych;
  • pobieranie katalogu;
  • włączanie/wyłączanie sprzedaży;
  • publikacja/ukrywanie produktów.

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 zamówień do systemu magazynowego;
  • aktualizacja statusu realizacji;
  • wysyłka numeru trackingowego;
  • synchronizacja referencji płatności.

Customers

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

Wymagane scope'y:

  • dane klientów: customers:read;
  • zamówienia klienta: orders:read.

Zastosowania:

  • raportowanie klientów;
  • integracje CRM;
  • historia zakupów.

Webhooki outbound

Webhooki wychodzące nie są jeszcze częścią podstawowego publicznego API. To będzie osobny moduł integracyjny, włączany wtedy, gdy klient potrzebuje powiadomień push zamiast okresowego pobierania danych.

Przykładowe przyszłe zdarzenia:

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

Zasady bezpiecznego dostępu

Publiczny dostęp do API powinien być włączany tylko dla konkretnych integracji. Standard bezpieczeństwa obejmuje:

  • osobny token dla każdej integracji;
  • ograniczone zakresy uprawnień, np. tylko odczyt zamówień albo tylko stany magazynowe;
  • limity zapytań, żeby zewnętrzny system nie przeciążył sklepu;
  • log audytu pokazujący kto i kiedy użył API;
  • kontrakt /api/v1 i dokument OpenAPI dla programisty integracji;
  • możliwość rotacji albo unieważnienia tokenu bez wpływu na panel sklepu;
  • minimalny zakres danych osobowych przekazywany do zewnętrznego systemu.

Jeżeli sklep potrzebuje integracji z ERP, magazynem, CRM albo marketplace, najbezpieczniej zacząć od ustalenia, które dane mają być odczytywane, które zapisywane i czy integracja ma działać jednokierunkowo czy dwukierunkowo.

Wewnętrzne API panelu

Poniższe endpointy obsługują panel sklepu i nie stanowią stabilnego kontraktu dla integracji zewnętrznych. Do połączeń z ERP, raportowania i pracy z katalogiem używaj publicznych endpointów opisanych powyżej.

Stan panelu

GET /shop/admin/state

Zwraca stan startowy panelu sklepu:

  • aktywny pakiet i capabilities;
  • uprawnienia zalogowanego użytkownika;
  • zespół;
  • ustawienia;
  • operacje;
  • compliance;
  • demo;
  • transfery;
  • słowniki i metadane UI.

GET /shop/admin/dashboard

Zwraca dane dashboardu:

  • liczby zamówień;
  • statusy płatności i realizacji;
  • produkty z niskim stanem;
  • zadania personalizacji;
  • opinie;
  • podstawowe wskaźniki sprzedaży.

Produkty

GET /shop/admin/products

Zwraca produkty do grida panelu. Dane obejmują m.in. trasę, tytuł, SKU, widoczność, aktywność sprzedaży, stan, warianty, typ produktu i partnera realizacyjnego.

Przykładowe zastosowania:

  • lista produktów w panelu;
  • filtrowanie katalogu;
  • szybka kontrola stanów;
  • 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 produktów. Używane do publikacji, ukrywania, włączania lub wyłączania sprzedaży oraz zapisu zmian w widoku produktów.

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 mieć powód albo notatkę. Zmiana zapisuje ruch magazynowy i audit log.

Zamówienia

GET /shop/admin/orders/{orderId}

Zwraca szczegół zamówienia:

  • klient;
  • adres rozliczeniowy i dostawy;
  • pozycje;
  • płatność;
  • dostawa;
  • dokumenty;
  • fulfillment;
  • personalizacja;
  • historia;
  • tracking;
  • dostępne akcje workflow.

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

Uruchamia akcje workflow zamówienia. Dostępne akcje zależą od statusu i uprawnień. Przykłady:

  • oznaczenie jako w realizacji;
  • oznaczenie jako wysłane;
  • oznaczenie jako zakończone;
  • anulowanie;
  • oznaczenie płatności.

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

Zapisuje tracking zamówienia.

Przykładowe 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 fakturę PDF z prywatnego storage.

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

Generuje albo pobiera PDF zamówienia.

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 zamówienia.

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

Wysyła projekt do akceptacji klienta albo zapisuje kolejna wersje projektu. Dotyczy procesów personalizacji w pakiecie PRO.

Fulfillment PRO

Endpointy fulfillmentu służą do obsługi realizacji dzielonych między partnerów.

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;
  • zakończone.

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

Zespół 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 pracowników;
  • aktualizacja roli i uprawnień;
  • usuwanie albo dezaktywacja pracownika;
  • włączanie i wymuszanie 2FA;
  • konfiguracja 2FA dla aktualnego użytkownika.

Ustawienia

PATCH /shop/admin/settings

Zapisuje ustawienia sklepu:

  • wygląd i publiczna część sklepu;
  • homepage;
  • kanały i trasy;
  • treści stron i e-maili;
  • dostawy;
  • płatności;
  • walutę;
  • faktury;
  • SEO, sitemap i merchant feed;
  • analytics i cookie consent;
  • typy produktów;
  • producenci;
  • partnerzy realizacyjni w PRO;
  • bezpieczne ustawienia wydajności.

Uploady

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

Uploady są przeznaczone dla panelu. Zewnętrzne integracje nie powinny ich używać bez osobnego kontraktu.

Compliance

GET /shop/admin/compliance/state

Zwraca checklisty i statusy:

  • SEO;
  • sitemap;
  • schema.org;
  • etykiety formularzy;
  • ARIA i dostępność;
  • 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 mogą obejmować zamówienia, realizacje albo paczkę danych sklepu.

Demo

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

Instalacja demo dodaje przykładowe dane. Czyszczenie demo nie powinno usuwać kont, sekretów, ustawień płatności, konfiguracji Mail ani realnych zamówień.

Kanały i języki

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

Kanał językowy może mieć osobne trasy, walutę, treści stron i teksty e-maili. Usunięcie kanału jest blokowane, jeżeli istnieją produkty albo dane zależne.

Transfer produktów 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. Uzupełnij produkty i media.
  3. Wgraj plik.
  4. Uruchom preview.
  5. Popraw błędy walidacji.
  6. Dopiero potem wykonaj import.

Publiczne feedy

To nie są endpointy /api/v1, ale są ważne dla integracji:

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

Sitemap służy wyszukiwarkom. Merchant feed jest przeznaczony dla katalogów produktowych i reklam.