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.

Podczas instalacji moduł tworzy swoje tabele, rejestruje hooki i dodaje menu Katalog > Klucze licencyjne. Generuje też sekret szyfrowania unikalny dla sklepu.

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”.

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).

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.