Licentiesleutels en digitale producten: documentatie DataFirefly License Keys

Installatie

Installeer de module via Modules > Modulebeheer > Module uploaden met het ZIP-bestand, of kopieer de map dflicensekeys naar de map /modules/ van de winkel en klik op Installeren. De PHP-extensie openssl is vereist.

Bij de installatie maakt de module zijn tabellen aan, registreert zijn hooks en voegt het menu Catalogus > Licentiesleutels toe. Ook maakt hij een versleutelingsgeheim aan dat uniek is voor de winkel.

Bij het de-installeren blijven sleutels, leveringen en geheim bewaard, zodat een reset van de module je voorraad niet leegmaakt. Schakel Alle sleutels, leveringen en bestanden verwijderen bij het de-installeren alleen in als je alles wilt wissen.

Module-instellingen

Levering

• Leveren wanneer de bestelling deze status bereikt: statussen die als betaald zijn gemarkeerd (Betaling geaccepteerd, Betaling op afstand geaccepteerd, Verzonden, Afgeleverd…) worden bij de installatie aangevinkt. Een overgang naar een van deze statussen start de levering. De verwerking is idempotent: opnieuw door zo’n status gaan stuurt geen nieuwe sleutels.
• Melding van directe levering tonen op productpagina’s: klein kader onder de prijs van digitale producten.
• Een kopie van de leveringsmails naar het waarschuwingsadres sturen: bcc naar het eerste waarschuwingsadres.

Annuleringen en terugbetalingen

Met automatisch intrekken ingeschakeld worden bij een bestelling die op Geannuleerd of Terugbetaald komt (standaardstatussen) de sleutels ingetrokken en de downloads geblokkeerd. Ingetrokken sleutels gaan nooit vanzelf terug naar de voorraad.

Sleutelvoorraad

• Producthoeveelheid synchroniseren met de beschikbare sleutels: de PrestaShop-hoeveelheid wordt het aantal werkelijk vrije sleutels, dus de beschikbare sleutels min die gereserveerd door nog niet geleverde bestellingen (een openstaande overschrijving, bijvoorbeeld) en min de ontbrekende sleutels van wachtende bestellingen. Met meerdere sleutels per eenheid wordt de hoeveelheid daarnaar gedeeld.
• Drempel voor lage voorraad (standaard 5) en E-mailadres(sen) voor waarschuwingen: er gaat een waarschuwing uit als de beschikbare sleutels tot deze drempel dalen of een bestelling op sleutels wacht, hooguit één keer per dag per product.

Standaardwaarden voor nieuwe digitale producten

Downloadlimiet (standaard 5, 0 = onbeperkt) en Geldigheid van de link in dagen (0 = verloopt niet), overgenomen bij het inschakelen van een product.

Licentie-API en activeringen

Zie het onderdeel API hieronder. Klanten laten activeringen vrijmaken via hun account staat standaard aan.

Een digitaal product instellen

Open de productpagina, tabblad Modules, blok Digitale levering en licentiesleutels. Het blok wordt opgeslagen met een eigen knop Digitale instellingen opslaan, los van het productformulier. Tot je klikt, staat er „Niet-opgeslagen wijzigingen”.

Stel het product in als virtueel product zodat bij het afrekenen niet om verzending wordt gevraagd. Het blok herinnert je eraan als dat niet zo is.

Licentiesleutels

• Bron van de sleutels: alleen geïmporteerde voorraad; geïmporteerde voorraad, daarna automatisch genereren als die leeg is; altijd automatisch gegenereerd.
• Sleutelpatroon: gebruikt door de generator. X = letter of cijfer, A = letter, 9 = cijfer, andere tekens blijven ongewijzigd. Minstens 8 willekeurige tekens, maximaal 128. Verwarrende tekens (0, O, 1, I) worden nooit gebruikt.
• Geldigheid van de licentie (dagen): 0 = levenslange licentie. De einddatum wordt berekend bij de levering van elke sleutel.
• Maximaal aantal activeringen per sleutel: 0 = onbeperkt. Afgedwongen door de licentie-API.
• Sleutels per bestelde eenheid: 5 voor een pakket van 5 licenties, bijvoorbeeld.
• Drempel voor lage voorraad: laat leeg om de algemene instelling te gebruiken.
• Voor elke combinatie een aparte sleutelvoorraad beheren: handig voor „1 jaar” en „3 jaar”, of „Windows” en „Mac”.

Downloadbaar bestand

Upload het bestand (installatieprogramma, pdf, archief). Het wordt in de map /download/ van PrestaShop opgeslagen onder een willekeurige naam en is nooit rechtstreeks bereikbaar. Stel de downloadlimiet per bestelregel en de geldigheid van de link in. Het vervangen van het bestand geldt ook voor klanten die al geleverd zijn.

Activeringsinstructies

Optionele tekst per taal, getoond bij de sleutels in de e-mail en in het klantaccount. Een groen bolletje markeert de ingevulde talen.

Sleutels importeren en genereren

Vanaf de productpagina (blok Sleutels aan de voorraad toevoegen) of via Catalogus > Licentiesleutels > Sleutels importeren:

• Plak de sleutels, één per regel, of kies een TXT-bestand (één sleutel per regel) of een CSV-bestand (sleutels in de eerste kolom, scheidingsteken ;, , of tab). Vink zo nodig De eerste regel van het bestand is een koptekst aan.
• Kies bij een product dat per combinatie wordt beheerd de combinatie.
• De batchnaam (bijvoorbeeld de leveranciersfactuur) helpt je deze sleutels later terug te vinden of te exporteren.

Duplicaten, al op voorraad voor dit product of herhaald in de lijst, worden overgeslagen. Sleutels langer dan 1000 tekens worden geweigerd. Een product dat nog niet was ingesteld, wordt ingeschakeld met de standaardinstellingen. Bestellingen die op sleutels wachten, worden direct na de import geleverd, de oudste eerst.

Om een batch in de voorraad te genereren (tot 10.000 sleutels), vul je het aantal en het patroon in en klik je op Genereren. Handig om je eigen licentiesysteem of een wederverkoper te voeden via de CSV-export.

Wat de klant ontvangt

• Leveringsmail in de taal van de bestelling: sleutels, geldigheid, downloadknop met het resterende aantal, activeringsinstructies. Er gaat een nieuwe e-mail uit telkens als er nieuwe sleutels worden toegewezen (latere levering of vervanging).
• Bevestigingspagina van de bestelling: de sleutels verschijnen meteen bij een directe betaling, anders meldt een bericht dat ze na de betalingsbevestiging worden verstuurd.
• Mijn account > Mijn licentiesleutels: alle sleutels van alle bestellingen, met kopieerknop, downloadlinks, geldigheid en geactiveerde apparaten. De link verschijnt alleen voor klanten die minstens één levering hebben ontvangen.
• Besteldetail en gastbestellingen: de sleutels en downloads van de bestelling. Een gastklant krijgt de link om de bestelling te volgen in de e-mail.

Een verlopen of opgebruikte downloadlink toont een duidelijke melding die de klant vraagt contact op te nemen.

Een bestelling beheren in de back-office

Op de bestelpagina toont het paneel Licentiesleutels en downloads elke digitale regel met de sleutels, hun geldigheid, de geactiveerde apparaten, de downloads en de vijf laatste toegangen (datum, IP).

• Nu leveren / opnieuw proberen: verwerkt de bestelling ongeacht de status. Handig voor een bestelling van vóór het inschakelen van het product, of als de medewerker die de status wijzigde geen rechten op de module heeft (PrestaShop voert de hooks van de module dan niet uit).
• E-mail opnieuw verzenden.
• Een sleutel vervangen: hij wordt ingetrokken en de klant krijgt een nieuwe.
• Downloads resetten: zet de teller op nul en verlengt de link met de geldigheid van het product.
• Activeringen resetten voor een sleutel.
• Alles intrekken en Opnieuw activeren: opnieuw activeren herstelt de sleutels die met de bestelling zijn ingetrokken, niet de handmatig vervangen sleutels.

Pagina Catalogus > Licentiesleutels

Sleutels

De tabel Voorraad per product geeft per product de beschikbare, geleverde en ingetrokken sleutels en de wachtende regels. Producten met een lage voorraad worden gemarkeerd. De sleutellijst is te filteren op product, status, exacte sleutel, bestelreferentie of -ID en batch. Sleutels zijn standaard gemaskeerd (oogknop om ze te tonen, kopieerknop). Acties: intrekken en vervangen, een ingetrokken sleutel terug op voorraad zetten, een beschikbare of ingetrokken sleutel verwijderen, activeringen resetten, CSV-export van de gefilterde sleutels.

Leveringen

Alle geleverde of wachtende regels, wachtende eerst, te filteren op status, bestelreferentie of -ID of e-mail van de klant. Acties: opnieuw proberen, opnieuw verzenden, downloads resetten.

Licentie-API

Schakel Licentie-API inschakelen in bij de instellingen. De configuratiepagina toont het adres van de API, een curl-voorbeeld en de lijst met foutcodes.

Endpoint: https://jouw-winkel.nl/module/dflicensekeys/api (POST of GET). Parameters:

• action: validate, activate of deactivate.
• license_key: de sleutel die de klant heeft ingevoerd.
• instance: unieke identificatie van het apparaat, domein of de installatie, verplicht voor activate en deactivate.
• label: optionele leesbare naam die de klant ziet („Kantoor-pc”).
• product_id: optioneel, beperkt de controle tot één product.
• secret: alleen verplicht als API-geheim verplicht stellen aan staat. Schakel dit in als alleen je eigen server de API aanroept, niet als de software hem vanaf de computer van de klant aanroept.

Het JSON-antwoord bevat success, error en een object license: status (active, revoked, expired), product_id, product_name, purchased_at, expires_at, max_activations, activations, activated.

curl -X POST "https://jouw-winkel.nl/module/dflicensekeys/api" 
  -d action=activate 
  -d license_key=ABCD-EFGH-JKLM-NPQR 
  -d instance=7f3c9a1e-werkplek 
  -d label="Kantoor-pc"

Foutcodes: 404 invalid_license (onbekende of nog niet verkochte sleutel), 403 license_revoked of license_expired, 403 activation_limit_reached, 400 missing_instance of unknown_action, 401 invalid_secret, 429 too_many_failed_attempts (meer dan 30 mislukte pogingen per uur vanaf hetzelfde IP).

AVG en hooks voor ontwikkelaars

Met de officiële module psgdpr bevat de gegevensexport van een klant zijn sleutels, de data, de downloads en de geactiveerde apparaten. Bij het verwijderen van een klant worden zijn leveringen en activeringen geanonimiseerd en wordt het downloadlog gewist: de sleutels blijven geldig, want ze zijn betaald.

Met twee hooks koppel je een CRM of een externe licentieserver:

• actionDfLicenseKeysDelivered: id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (sleutels in platte tekst).
• actionDfLicenseKeysRevoked: id_order.

Probleemoplossing

De klant heeft zijn sleutels niet ontvangen

Controleer of de bestelstatus is aangevinkt bij Leveren wanneer de bestelling deze status bereikt en klik in de bestelling op Nu leveren / opnieuw proberen. Toont het paneel geleverde sleutels, klik dan op E-mail opnieuw verzenden en controleer de e-mailinstellingen van PrestaShop.

Bestellingen blijven op „Wacht op sleutels” staan

De voorraad van het product (of de combinatie) is leeg. Importeer sleutels: wachtende bestellingen gaan automatisch de deur uit. Controleer of de optie per combinatie klopt met de combinatie waarin je importeert.

Sleutels verschijnen als „[?]” met een rode banner

De cookiesleutel van de winkel of de instelling DFLK_SECRET is gewijzigd, vaak na een verhuizing. Zet het vorige bestand parameters.php terug.

De downloadlink meldt dat het bestand niet beschikbaar is

Het bestand is van het product gehaald of uit de map /download/ verwijderd. Upload het opnieuw via het tabblad Modules van het product.

De producthoeveelheid is negatief

Er wachten bestellingen op meer sleutels dan de voorraad bevat. Importeer sleutels, dan stijgt de hoeveelheid vanzelf.

Compatibiliteit

• PrestaShop 8.0 tot 9.x, dezelfde ZIP dekt beide versies, oude en nieuwe productpagina.
• Architectuur ModuleAdminController, zonder Composer-afhankelijkheid, PHP 7.2 en hoger, extensie openssl.
• Interface en e-mails in het Frans, Engels, Spaans, Duits, Italiaans, Nederlands, Pools en Portugees.