# Klucze licencyjne i produkty cyfrowe: dokumentacja DataFirefly License Keys > Instalacja Zainstaluj moduł w Moduły > Menedżer modułów > Prześlij moduł, wybierając plik ZIP, albo skopiuj folder dflicensekeys do katalogu /modules/ sklepu i kliknij Zainstaluj. Wymagane jest rozszerzenie PHP openssl.… - Strona: - Język: pl - Zaktualizowano: 2026-09-23 - Inne języki: [fr](https://www.datafirefly.com/documentation/dflicensekeys/index.md), [en](https://www.datafirefly.com/en/documentation/dflicensekeys/index.md), [es](https://www.datafirefly.com/es/documentation/dflicensekeys/index.md), [de](https://www.datafirefly.com/de/documentation/dflicensekeys/index.md), [it](https://www.datafirefly.com/it/documentation/dflicensekeys/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflicensekeys/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflicensekeys/index.md) - Indeks: ## Instalacja Zainstaluj moduł w **Moduły > Menedżer modułów > Prześlij moduł**, wybierając plik ZIP, albo skopiuj folder `dflicensekeys` do katalogu `/modules/` sklepu i kliknij Zainstaluj. Wymagane jest rozszerzenie PHP `openssl`. Podczas instalacji moduł tworzy swoje tabele, rejestruje hooki i dodaje menu **Katalog > Klucze licencyjne**. Generuje też sekret szyfrowania unikalny dla sklepu. Klucze są szyfrowane kluczem, który łączy klucz cookie PrestaShop (plik `app/config/parameters.php`) z tym sekretem. Przy migracji lub kopiowaniu sklepu zachowaj ten plik parametrów: bez niego klucze stają się nieczytelne. Czerwony baner ostrzega, gdy tak się stanie. Odinstalowanie zachowuje klucze, dostawy i sekret, aby reset modułu nie opróżnił magazynu. Włącz **Usuń wszystkie klucze, dostawy i pliki przy odinstalowaniu** tylko wtedy, gdy chcesz wszystko skasować. ## Ustawienia modułu ### Dostawa - **Dostarczaj, gdy zamówienie osiągnie status**: statusy oznaczone jako opłacone (Płatność zaakceptowana, Płatność zdalna zaakceptowana, Wysłane, Dostarczone…) są zaznaczane podczas instalacji. Zmiana na jeden z nich uruchamia dostawę. Przetwarzanie jest idempotentne: ponowne przejście przez taki status nie wysyła nowych kluczy. - **Pokazuj informację o natychmiastowej dostawie na stronach produktów**: małe pole pod ceną produktów cyfrowych. - **Wysyłaj kopię e-maili z dostawą na adres alertów**: ukryta kopia na pierwszy adres alertów. ### Anulowania i zwroty Przy włączonym automatycznym unieważnianiu zamówienie, które przechodzi w status Anulowane lub Zwrócone (statusy domyślne), ma unieważnione klucze i zablokowane pobrania. Unieważnione klucze nigdy same nie wracają do magazynu. ### Magazyn kluczy - **Synchronizuj ilość produktu z dostępnymi kluczami**: ilość w PrestaShop odpowiada liczbie faktycznie wolnych kluczy, czyli dostępnym kluczom minus klucze zarezerwowane przez niedostarczone jeszcze zamówienia (np. oczekujący przelew) i minus klucze brakujące w oczekujących zamówieniach. Przy kilku kluczach na sztukę ilość jest odpowiednio dzielona. - **Próg alertu niskiego stanu** (domyślnie 5) i **Adres(y) e-mail alertów**: alert jest wysyłany, gdy liczba dostępnych kluczy spadnie do tego progu lub gdy zamówienie czeka na klucze, najwyżej raz dziennie na produkt. ### Domyślne ustawienia nowych produktów cyfrowych **Limit pobrań** (domyślnie 5, 0 = bez limitu) i **Ważność linku** w dniach (0 = bez wygaśnięcia), stosowane przy włączeniu produktu. ### API licencji i aktywacje Zobacz sekcję API poniżej. Opcja **Pozwól klientom zwalniać aktywacje na ich koncie** jest domyślnie włączona. ## Konfiguracja produktu cyfrowego Otwórz stronę produktu, zakładka **Moduły**, blok **Dostawa cyfrowa i klucze licencyjne**. Blok zapisuje się własnym przyciskiem **Zapisz ustawienia cyfrowe**, niezależnie od formularza produktu. Dopóki go nie klikniesz, widoczny jest komunikat „Niezapisane zmiany”. Ustaw typ produktu na **Produkt wirtualny**, aby przy zamówieniu nie była wymagana wysyłka. Blok przypomni o tym, jeśli tak nie jest. ### Klucze licencyjne - **Źródło kluczy**: tylko zaimportowany magazyn; zaimportowany magazyn, a po jego wyczerpaniu automatyczne generowanie; zawsze generowane automatycznie. - **Wzór klucza**: używany przez generator. `X` = litera lub cyfra, `A` = litera, `9` = cyfra, pozostałe znaki są zachowywane. Co najmniej 8 losowych znaków, maksymalnie 128. Mylące się znaki (0, O, 1, I) nigdy nie są losowane. - **Ważność licencji (dni)**: 0 = licencja dożywotnia. Data końcowa jest obliczana przy dostawie każdego klucza. - **Maksymalna liczba aktywacji na klucz**: 0 = bez limitu. Egzekwowane przez API licencji. - **Kluczy na zamówioną sztukę**: np. 5 dla pakietu 5 licencji. - **Próg alertu niskiego stanu**: pozostaw puste, aby użyć ustawienia globalnego. - **Osobny magazyn kluczy dla każdej kombinacji**: przydatne dla „1 rok” i „3 lata” albo „Windows” i „Mac”. Przy automatycznym generowaniu magazyn nigdy się nie kończy: ilość produktu nie jest już synchronizowana. Ustaw dużą ilość lub zezwól na zamówienia bez stanu magazynowego. ### Plik do pobrania Prześlij plik (instalator, PDF, archiwum). Jest przechowywany w folderze `/download/` PrestaShop pod losową nazwą i nigdy nie jest dostępny bezpośrednio. Ustaw **limit pobrań na pozycję zamówienia** i **ważność linku**. Zastąpienie pliku obejmuje też klientów już obsłużonych. ### Instrukcja aktywacji Opcjonalny tekst w każdym języku, wyświetlany z kluczami w e-mailu i na koncie klienta. Zielona kropka oznacza wypełnione języki. ## Import i generowanie kluczy Ze strony produktu (blok **Dodaj klucze do magazynu**) lub z **Katalog > Klucze licencyjne > Importuj klucze**: - Wklej klucze, jeden w wierszu, lub wybierz plik TXT (jeden klucz w wierszu) albo CSV (klucze w pierwszej kolumnie, separator `;`, `,` lub tabulator). W razie potrzeby zaznacz **Pierwszy wiersz pliku to nagłówek**. - Dla produktu zarządzanego według kombinacji wybierz kombinację. - **Nazwa partii** (np. faktura dostawcy) pozwala później odnaleźć lub wyeksportować te klucze. Duplikaty, już obecne w magazynie tego produktu lub powtórzone na liście, są pomijane. Klucze dłuższe niż 1000 znaków są odrzucane. Nieskonfigurowany jeszcze produkt zostaje włączony z ustawieniami domyślnymi. Zamówienia czekające na klucze są realizowane zaraz po imporcie, od najstarszych. Aby wygenerować partię do magazynu (do 10 000 kluczy), podaj liczbę i wzór, a następnie kliknij **Generuj**. Przydatne do zasilenia własnego systemu licencji lub odsprzedawcy przez eksport CSV. ## Co otrzymuje klient - **E-mail z dostawą** w języku zamówienia: klucze, ważność, przycisk pobierania z pozostałą liczbą pobrań, instrukcja aktywacji. Nowy e-mail jest wysyłany za każdym razem, gdy przypisywane są nowe klucze (dostawa odroczona lub wymiana). - **Strona potwierdzenia zamówienia**: klucze pojawiają się od razu przy płatności natychmiastowej, w przeciwnym razie komunikat informuje, że zostaną wysłane po potwierdzeniu płatności. - **Moje konto > Moje klucze licencyjne**: wszystkie klucze ze wszystkich zamówień, z przyciskiem kopiowania, linkami do pobrania, ważnością i aktywowanymi urządzeniami. Link pojawia się tylko klientom, którzy otrzymali co najmniej jedną dostawę. - **Szczegóły zamówienia i śledzenie dla gości**: klucze i pobrania zamówienia. Klient-gość dostaje link do śledzenia w e-mailu. Wygasły lub wykorzystany link do pobrania wyświetla czytelny komunikat z prośbą o kontakt. ## Zarządzanie zamówieniem w panelu Na stronie zamówienia panel **Klucze licencyjne i pobrania** pokazuje każdą pozycję cyfrową z kluczami, ich ważnością, aktywowanymi urządzeniami, pobraniami i pięcioma ostatnimi dostępami (data, IP). - **Dostarcz teraz / ponów**: przetwarza zamówienie niezależnie od statusu. Przydatne dla zamówienia złożonego przed włączeniem produktu lub gdy pracownik, który zmienił status, nie ma uprawnień do modułu (PrestaShop nie wykonuje wtedy hooków modułu). - **Wyślij e-mail ponownie**. - **Zastąp** klucz: zostaje unieważniony, a klient otrzymuje nowy. - **Zeruj pobrania**: ustawia licznik na zero i przedłuża link o okres ważności produktu. - **Resetuj aktywacje** klucza. - **Unieważnij wszystko** i **Aktywuj ponownie**: ponowna aktywacja przywraca klucze unieważnione razem z zamówieniem, a nie te wymienione ręcznie. ## Strona Katalog > Klucze licencyjne ### Klucze Tabela **Stan według produktu** pokazuje dla każdego produktu klucze dostępne, dostarczone i unieważnione oraz oczekujące pozycje. Produkty z niskim stanem są wyróżnione. Listę kluczy można filtrować według produktu, statusu, dokładnego klucza, numeru lub ID zamówienia i partii. Klucze są domyślnie zamaskowane (przycisk oka, aby je pokazać, przycisk kopiowania). Akcje: unieważnij i zastąp, przywróć unieważniony klucz do magazynu, usuń klucz dostępny lub unieważniony, resetuj aktywacje, eksport CSV przefiltrowanych kluczy. ### Dostawy Wszystkie pozycje dostarczone lub oczekujące, najpierw oczekujące, z filtrem według statusu, numeru lub ID zamówienia albo e-maila klienta. Akcje: ponów, wyślij ponownie, zeruj pobrania. ## API licencji Włącz **Włącz API licencji** w ustawieniach. Strona konfiguracji pokazuje adres API, przykład curl i listę kodów błędów. Adres końcowy: `https://twoj-sklep.pl/module/dflicensekeys/api` (POST lub GET). Parametry: - `action`: `validate`, `activate` lub `deactivate`. - `license_key`: klucz wprowadzony przez klienta. - `instance`: unikalny identyfikator urządzenia, domeny lub instalacji, wymagany dla activate i deactivate. - `label`: opcjonalna czytelna nazwa widoczna dla klienta („Komputer biurowy”). - `product_id`: opcjonalnie, ogranicza weryfikację do jednego produktu. - `secret`: wymagany tylko przy włączonej opcji **Wymagaj sekretu API**. Włącz ją, gdy API wywołuje wyłącznie Twój serwer, a nie program z komputera klienta. Odpowiedź JSON zawiera `success`, `error` i obiekt `license`: `status` (active, revoked, expired), `product_id`, `product_name`, `purchased_at`, `expires_at`, `max_activations`, `activations`, `activated`. ``` curl -X POST "https://twoj-sklep.pl/module/dflicensekeys/api" -d action=activate -d license_key=ABCD-EFGH-JKLM-NPQR -d instance=7f3c9a1e-stanowisko -d label="Komputer biurowy" ``` Kody błędów: 404 `invalid_license` (nieznany lub jeszcze niesprzedany klucz), 403 `license_revoked` lub `license_expired`, 403 `activation_limit_reached`, 400 `missing_instance` lub `unknown_action`, 401 `invalid_secret`, 429 `too_many_failed_attempts` (ponad 30 nieudanych prób na godzinę z tego samego IP). Wywołaj `activate` przy pierwszym wpisaniu klucza, a potem `validate` z tym samym `instance` przy każdym uruchomieniu programu. Aktywacja już zapisana dla tego urządzenia nigdy nie jest liczona dwa razy. ## RODO i hooki dla programistów Z oficjalnym modułem psgdpr eksport danych klienta obejmuje jego klucze, daty, pobrania i aktywowane urządzenia. Usunięcie klienta anonimizuje jego dostawy i aktywacje oraz kasuje dziennik pobrań: klucze pozostają ważne, ponieważ zostały opłacone. Dwa hooki pozwalają podłączyć CRM lub zewnętrzny serwer licencji: - `actionDfLicenseKeysDelivered`: id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (klucze w postaci jawnej). - `actionDfLicenseKeysRevoked`: id_order. ## Rozwiązywanie problemów ### Klient nie otrzymał kluczy Sprawdź, czy status zamówienia jest zaznaczony w **Dostarczaj, gdy zamówienie osiągnie status**, a następnie kliknij **Dostarcz teraz / ponów** w zamówieniu. Jeśli panel pokazuje dostarczone klucze, kliknij **Wyślij e-mail ponownie** i sprawdź konfigurację e-mail PrestaShop. ### Zamówienia pozostają w stanie „Oczekuje na klucze” Magazyn produktu (lub kombinacji) jest pusty. Zaimportuj klucze: oczekujące zamówienia zostaną wysłane automatycznie. Sprawdź, czy opcja dla kombinacji odpowiada kombinacji, do której importujesz. ### Klucze wyświetlają się jako „[?]” z czerwonym banerem Zmienił się klucz cookie sklepu lub ustawienie `DFLK_SECRET`, często po migracji. Przywróć poprzedni plik `parameters.php`. ### Link do pobrania informuje, że plik jest niedostępny Plik został usunięty z produktu lub z folderu `/download/`. Prześlij go ponownie w zakładce Moduły produktu. ### Ilość produktu jest ujemna Zamówienia czekają na więcej kluczy, niż jest w magazynie. Zaimportuj klucze, a ilość sama wzrośnie. ## Zgodność - PrestaShop od 8.0 do 9.x, ten sam plik ZIP obsługuje obie gałęzie, starą i nową stronę produktu. - Architektura ModuleAdminController, bez zależności Composer, PHP 7.2 i nowszy, rozszerzenie openssl. - Interfejs i e-maile po francusku, angielsku, hiszpańsku, niemiecku, włosku, niderlandzku, polsku i portugalsku.