Klucze API

Klucze API pozwalają połączyć Twój sklep z zewnętrznym oprogramowaniem - na przykład systemem magazynowym, programem księgowym czy systemem ERP - tak aby te programy mogły automatycznie odczytywać i aktualizować dane sklepu bez logowania do panelu.

Jak to działa

Klucz API to długi, poufny ciąg znaków, który działa jak hasło dla programu. Gdy przekażesz klucz swojemu integratorowi (np. firmie wdrażającej system magazynowy), jego oprogramowanie używa go do bezpiecznego łączenia się z Twoim sklepem. Każdy klucz ma dokładnie określony zakres uprawnień - sam decydujesz, co dany program może robić: tylko odczytywać dane, czy także je zmieniać.

Klucze nie dają dostępu do panelu administracyjnego ani do ustawień rozliczeń - służą wyłącznie do automatycznej wymiany danych handlowych (produkty, zamówienia, klienci, stany magazynowe).

Generowanie klucza

Ustawienia → Klucze API → Utwórz klucz

1. Nadaj kluczowi czytelną nazwę (np. „System magazynowy" albo „Integracja z księgowością") - ułatwi Ci później rozpoznanie, do czego służy.
2. Zaznacz uprawnienia, których klucz ma wymagać (patrz Uprawnienia).
3. Opcjonalnie ustaw datę ważności, dozwolone adresy IP i limit zapytań.
4. Kliknij Utwórz.

Klucz zobaczysz tylko raz

Pełny klucz jest wyświetlany jednokrotnie, bezpośrednio po utworzeniu. Skopiuj go od razu i przekaż integratorowi bezpiecznym kanałem. Po zamknięciu okna nie da się go odczytać ponownie - w panelu widoczny jest jedynie skrócony identyfikator (pierwszych kilkanaście znaków), który służy do rozpoznania klucza na liście. Jeśli zgubisz klucz, wykonaj rotację lub utwórz nowy.

Klucz ma postać sk_live_ i dalszego ciągu losowych znaków. W panelu nigdy nie jest przechowywany w czytelnej formie - zapisywany jest wyłącznie jego zaszyfrowany skrót, dzięki czemu nawet zespół platformy nie odczyta Twojego klucza.

Uprawnienia

Dla każdego klucza wybierasz uprawnienia osobno dla każdego obszaru danych. W każdym obszarze rozróżniamy dwa poziomy: Odczyt (program może tylko pobierać dane) oraz Zapis (program może też tworzyć i zmieniać dane).

Obszar	Odczyt pozwala	Zapis pozwala
Produkty	przeglądać katalog i warianty	dodawać, edytować i usuwać produkty
Zamówienia	przeglądać zamówienia i ich statusy	zmieniać status zamówienia, status realizacji, anulować, edytować etykiety
Klienci	przeglądać dane klientów	dodawać i edytować klientów
Stany magazynowe	sprawdzać dostępność i historię ruchów	korygować stany magazynowe
Atrybuty	przeglądać cechy produktów (np. Producent, Materiał)	dodawać, edytować i usuwać definicje cech
Warianty	przeglądać warianty produktów	dodawać, edytować i usuwać warianty
Zdjęcia	sprawdzać status wgrywanych zdjęć	wgrywać, usuwać i porządkować zdjęcia produktów
Marki	przeglądać marki	dodawać, edytować i usuwać marki
Kategorie	przeglądać kategorie i ich strukturę	dodawać, edytować i usuwać kategorie
Specyfikacja produktu	przeglądać wartości cech wpisane przy produktach (np. Marka = „Hasbro", Liczba graczy = „2–6")	ustawiać i usuwać wartości cech przy produktach
Statystyki	przeglądać zbiorcze statystyki sklepu (sprzedaż, koszyki, klienci, stany katalogu)	- (obszar wyłącznie do odczytu)
Kody rabatowe	przeglądać kody rabatowe, ich warunki i liczbę użyć	tworzyć, edytować i usuwać kody rabatowe
Blog	przeglądać wpisy, kategorie i tagi bloga	tworzyć, edytować, publikować i usuwać wpisy, kategorie i tagi
Konfigurator dla klienta	przeglądać pola konfiguratora, zestawy atrybutów i nadpisania przy produktach	zarządzać konfiguratorem: pola z dopłatami i komponentami z magazynu, pod-komponenty, zestawy, nadpisania i ukrycia przy produktach, kopiowanie konfiguratora między produktami

Atrybuty a specyfikacja produktu

To dwa osobne obszary. Atrybuty to definicje cech - lista cech, które w ogóle istnieją w sklepie (np. „Producent", „Liczba graczy"). Specyfikacja produktu to konkretne wartości tych cech wpisane przy danym produkcie (np. Producent = „Hasbro"). Pierwsze uprawnienie pozwala zarządzać samą listą cech, drugie - wypełniać je przy produktach.

Atrybuty a konfigurator dla klienta

Uprawnienie Atrybuty obejmuje wyłącznie cechy wypełniane przez Ciebie (metadane). Pola, które wypełnia klient przy zakupie - wybory z dopłatą, komponenty z magazynu, pod-komponenty - to osobne uprawnienie Konfigurator dla klienta, bo wpływają na ceny w sklepie. Klucze utworzone przed pojawieniem się tego uprawnienia nie mają go - nadaj je świadomie tylko integracjom, które mają zarządzać konfiguratorem.

Zasada minimalnych uprawnień

Przyznawaj kluczowi tylko te uprawnienia, których integracja faktycznie potrzebuje. Jeśli program ma jedynie synchronizować stany magazynowe, nie nadawaj mu zapisu zamówień ani klientów. Im węższy zakres, tym mniejsze ryzyko w razie wycieku klucza.

Uprawnienie „Usuń"

Oprócz odczytu i zapisu niektóre obszary mają trzeci, wysokouprawniony poziom - Usuń. Kolumna „Usuń" pojawia się w macierzy uprawnień tylko przy tych obszarach, które mają operację trwałego kasowania - obecnie dotyczy to wyłącznie klientów.

Uprawnienie „Usuń" dla klientów pozwala integracji trwale usuwać konta klientów pochodzące z importu, które nie mają żadnej historii (zamówień, zwrotów, opinii, punktów lojalnościowych, poleceń). To narzędzie do porządkowania bazy po imporcie - np. usunięcia tysięcy fikcyjnych kont.

• Uprawnienie jest domyślnie wyłączone. Istniejące klucze nie zyskują go automatycznie - musisz je świadomie nadać.
• Zaznaczenie „Usuń" automatycznie włącza też „Odczyt" (odczyt jest fundamentem).
• Klienci z historią są przez API pomijani - nigdy anonimizowani. Anonimizacja pozostaje wyłącznie w panelu.

Uprawnienie nieodwracalne w skutkach

„Usuń" pozwala programowi trwale i bezpowrotnie kasować dane. Nadawaj je wyłącznie zaufanym integracjom, które naprawdę tego potrzebują.

Pozostałe operacje wrażliwe pozostają wyłącznie w panelu i nie są dostępne przez klucze API - w szczególności anonimizacja i eksport danych klientów (zgodność z RODO), zwroty i korekty płatności. Wymagają one zalogowanego pracownika, aby zachować pełną odpowiedzialność w dzienniku audytu.

Ważność klucza

Możesz ustawić datę, po której klucz automatycznie przestanie działać. To dobra praktyka dla integracji tymczasowych (np. jednorazowa migracja danych) lub gdy chcesz wymusić cykliczną wymianę kluczy. Klucz bez ustawionej daty ważności działa bezterminowo, dopóki go nie unieważnisz.

Ograniczenia adresów IP

Dla każdego klucza możesz wskazać listę dozwolonych adresów IP - wtedy klucz zadziała wyłącznie wtedy, gdy zapytanie pochodzi z jednego z tych adresów. Jeśli zostawisz listę pustą, klucz działa z dowolnego adresu.

To skuteczne zabezpieczenie, gdy Twój integrator korzysta ze stałego adresu serwera. Zapytanie z nieznanego adresu zostanie odrzucone, nawet jeśli klucz jest poprawny.

Limit zapytań

Limit zapytań określa, ile zapytań na minutę dany klucz może wykonać. Chroni to Twój sklep przed przeciążeniem przez błędnie działający program. Po przekroczeniu limitu kolejne zapytania są na chwilę wstrzymywane, a program otrzymuje informację, kiedy może spróbować ponownie.

Jeśli zostawisz to pole puste lub ustawisz na zero, obowiązuje domyślny limit platformy. W większości przypadków domyślna wartość jest wystarczająca - podnoś ją tylko, jeśli integrator zgłasza, że potrzebuje wyższej przepustowości.

Rotacja i unieważnianie

Akcja	Co robi	Kiedy używać
Rotacja	Generuje nowy klucz z tymi samymi ustawieniami i jednocześnie unieważnia stary. Nowy klucz zobaczysz tylko raz.	Gdy podejrzewasz, że klucz mógł wyciec, lub chcesz cyklicznie wymieniać klucze bez zmiany konfiguracji uprawnień.
Unieważnienie	Trwale wyłącza klucz. Wpis pozostaje na liście (dla historii), ale klucz natychmiast przestaje działać.	Gdy integracja nie jest już potrzebna lub klucz na pewno został ujawniony.

Unieważnienia nie da się cofnąć - unieważnionego klucza nie można ponownie aktywować ani edytować. Jeśli integracja ma wrócić, utwórz nowy klucz.

Statusy klucza

Na liście kluczy każdy wpis ma czytelny status:

Status	Znaczenie
Aktywny	Klucz działa i obsługuje zapytania.
Nieaktywny	Klucz został czasowo wyłączony (możesz go ponownie włączyć).
Wygasły	Minęła data ważności - klucz nie działa, dopóki nie wydłużysz terminu.
Unieważniony	Klucz został trwale wyłączony i nie da się go przywrócić.

Logi i audyt klucza

Dla każdego klucza możesz podejrzeć pełną historię jego użycia. Na liście kluczy rozwiń menu akcji przy wybranym kluczu i wybierz Logi i audyt - otworzy się boczny panel z dwiema zakładkami. Podgląd jest dostępny także dla kluczy unieważnionych, dzięki czemu możesz prześledzić, co działo się tym kluczem zanim go wyłączyłeś (przydatne przy podejrzeniu nadużycia).

Zakładka	Co pokazuje	Kolumny
Logi dostępu	Każde pojedyncze zapytanie wykonane kluczem - niezależnie od tego, czy coś zmieniło (również zwykłe odczyty danych)	czas, metoda, trasa, status, czas odpowiedzi, adres IP
Audyt zmian	Tylko operacje, które faktycznie coś zmieniły w sklepie (utworzenie, edycja, usunięcie, zmiana statusu)	czas, akcja, zasób, identyfikator zasobu, adres IP

Po co to:

• Diagnostyka integracji - gdy program integratora działa nieprawidłowo, widzisz dokładnie, jakie zapytania wysyła i jakie otrzymuje odpowiedzi.
• Wykrywanie nadużyć - nietypowy wzorzec zapytań albo zapytania z nieznanego adresu IP od razu rzucają się w oczy.
• Zgodność i kontrola - masz udokumentowane, który klucz i kiedy sięgał po dane, w tym dane osobowe klientów.

Najstarsze wpisy w Logach dostępu są po pewnym czasie automatycznie usuwane (domyślnie po 90 dniach) - to wyłącznie zapis samych zapytań. Audyt zmian (historia faktycznych zmian w sklepie) zachowywany jest dłużej, dopóki sklep istnieje.

Dobre praktyki bezpieczeństwa

• Traktuj klucz jak hasło - nie wysyłaj go zwykłym e-mailem ani nie publikuj w dokumentach współdzielonych. Użyj bezpiecznego kanału przekazania.
• Jeden klucz na jedną integrację - łatwiej wtedy unieważnić dostęp pojedynczego programu, nie zakłócając pozostałych.
• Nadawaj minimalne uprawnienia - tylko to, czego dana integracja realnie potrzebuje.
• Ograniczaj adresy IP, jeśli integrator korzysta ze stałego serwera.
• Wymieniaj klucze cyklicznie za pomocą rotacji, zwłaszcza dla długo działających integracji.
• Unieważniaj nieużywane klucze - każdy aktywny klucz to potencjalna furtka do danych sklepu.

Każda operacja na kluczach (utworzenie, zmiana, rotacja, unieważnienie) oraz każda nieudana próba uwierzytelnienia są zapisywane w historii bezpieczeństwa sklepu, więc zawsze możesz sprawdzić, co i kiedy się działo.

Sklep jest też automatycznie chroniony przed próbami zgadywania kluczy: po wielu nieudanych próbach uwierzytelnienia z tego samego adresu IP dostęp z niego zostaje na pewien czas zablokowany. Jeśli Twój integrator zgłasza taką blokadę, powinien sprawdzić poprawność klucza i odczekać wskazany czas, zamiast w kółko ponawiać połączenia.

Dla integratorów

Adres bazowy API to https://api.doswiftly.pl/merchant/v1. Klucz API sam wskazuje Twój sklep (identyfikator sklepu jest w nim zakodowany), więc nie podajesz go w adresie. Adres bazowy znajdziesz też w panelu: Klucze API → Zasoby dla deweloperów.

Interaktywną dokumentację API, w której można przeglądać i testować zapytania, znajdziesz pod adresami:

• Dokumentacja API: https://api.doswiftly.pl/merchant-api/reference
• Specyfikacja OpenAPI (JSON): https://api.doswiftly.pl/merchant-api-json

Pełny przewodnik (autoryzacja, limity, przykłady zapytań, kody błędów) znajduje się w sekcji dla deweloperów: Merchant API - referencja.