Claves de licencia y productos digitales: documentación de DataFirefly License Keys

Instalación

Instala el módulo desde Módulos > Gestor de módulos > Subir un módulo con el archivo ZIP, o copia la carpeta dflicensekeys en el directorio /modules/ de la tienda y haz clic en Instalar. Se requiere la extensión PHP openssl.

Al instalarse, el módulo crea sus tablas, registra sus hooks y añade el menú Catálogo > Claves de licencia. También genera un secreto de cifrado propio de la tienda.

La desinstalación conserva las claves, las entregas y el secreto, para que restablecer el módulo no vacíe tu stock. Activa Eliminar todas las claves, entregas y archivos al desinstalar solo si quieres borrarlo todo.

Ajustes del módulo

Entrega

• Entregar cuando el pedido pase a: los estados marcados como pagados (Pago aceptado, Pago remoto aceptado, Enviado, Entregado…) se seleccionan en la instalación. Un cambio a uno de ellos activa la entrega. El proceso es idempotente: volver a pasar por uno de estos estados no envía claves nuevas.
• Mostrar el aviso de entrega inmediata en las fichas de producto: pequeño recuadro bajo el precio de los productos digitales.
• Enviar una copia de los correos de entrega a la dirección de alerta: copia oculta a la primera dirección de alerta.

Cancelaciones y reembolsos

Con la revocación automática activada, un pedido que pasa a Cancelado o Reembolsado (estados por defecto) ve sus claves revocadas y sus descargas bloqueadas. Las claves revocadas nunca vuelven solas al stock.

Stock de claves

• Sincronizar la cantidad del producto con las claves disponibles: la cantidad de PrestaShop pasa a ser el número de claves realmente libres, es decir, las disponibles menos las reservadas por pedidos aún no entregados (una transferencia pendiente, por ejemplo) y menos las claves que faltan en los pedidos en espera. Con varias claves por unidad, la cantidad se divide en consecuencia.
• Umbral de alerta de stock bajo (5 por defecto) y Dirección(es) de correo de alerta: se envía una alerta cuando las claves disponibles bajan a ese umbral o un pedido espera claves, como máximo una vez al día por producto.

Valores por defecto de los nuevos productos digitales

Límite de descargas (5 por defecto, 0 = ilimitado) y Validez del enlace en días (0 = sin caducidad), aplicados al activar un producto.

API de licencias y activaciones

Consulta la sección API más abajo. La opción Permitir a los clientes liberar activaciones desde su cuenta está activada por defecto.

Configurar un producto digital

Abre la ficha del producto, pestaña Módulos, bloque Entrega digital y claves de licencia. El bloque se guarda con su propio botón Guardar los ajustes digitales, independiente del formulario del producto. Se muestra «Cambios sin guardar» mientras no hagas clic.

Define el producto como Producto virtual para que no se pida envío al pagar. El bloque te lo recuerda si no es así.

Claves de licencia

• Origen de las claves: solo stock importado; stock importado y, cuando se agota, generación automática; siempre generadas automáticamente.
• Patrón de clave: usado por el generador. X = letra o cifra, A = letra, 9 = cifra, el resto de caracteres se mantiene. Al menos 8 caracteres aleatorios, 128 como máximo. Los caracteres ambiguos (0, O, 1, I) nunca se usan.
• Validez de la licencia (días): 0 = licencia de por vida. La fecha de fin se calcula al entregar cada clave.
• Activaciones máximas por clave: 0 = ilimitado. Controlado por la API de licencias.
• Claves por unidad pedida: 5 para un pack de 5 licencias, por ejemplo.
• Umbral de alerta de stock bajo: déjalo vacío para usar el ajuste global.
• Gestionar un stock de claves distinto para cada combinación: útil para «1 año» y «3 años», o «Windows» y «Mac».

Archivo descargable

Sube el archivo (instalador, PDF, archivo comprimido). Se guarda en la carpeta /download/ de PrestaShop con un nombre aleatorio y nunca es accesible directamente. Ajusta el límite de descargas por línea de pedido y la validez del enlace. Sustituir el archivo beneficia también a los clientes ya servidos.

Instrucciones de activación

Texto opcional por idioma, mostrado con las claves en el correo y en la cuenta del cliente. Un punto verde señala los idiomas rellenados.

Importar y generar claves

Desde la ficha del producto (bloque Añadir claves al stock) o desde Catálogo > Claves de licencia > Importar claves:

• Pega las claves, una por línea, o elige un archivo TXT (una clave por línea) o CSV (claves en la primera columna, separador ;, , o tabulación). Marca La primera línea del archivo es una cabecera si hace falta.
• Para un producto gestionado por combinación, elige la combinación.
• El nombre del lote (factura del proveedor, por ejemplo) permite encontrar o exportar estas claves más adelante.

Los duplicados, ya en stock para este producto o repetidos en la lista, se omiten. Las claves de más de 1000 caracteres se rechazan. Un producto aún sin configurar se activa con los ajustes por defecto. Los pedidos que esperan claves se entregan al terminar la importación, los más antiguos primero.

Para generar un lote en el stock (hasta 10.000 claves), indica el número y el patrón y haz clic en Generar. Práctico para alimentar tu propio sistema de licencias o a un revendedor mediante la exportación CSV.

Lo que recibe el cliente

• Correo de entrega en el idioma del pedido: claves, validez, botón de descarga con el número restante, instrucciones de activación. Se envía un correo nuevo cada vez que se asignan claves nuevas (entrega diferida o sustitución).
• Página de confirmación del pedido: las claves aparecen directamente si el pago es inmediato; si no, un mensaje indica que se enviarán al confirmarse el pago.
• Mi cuenta > Mis claves de licencia: todas las claves de todos los pedidos, con botón de copiar, enlaces de descarga, validez y dispositivos activados. El enlace solo aparece a los clientes que han recibido al menos una entrega.
• Detalle del pedido y seguimiento de invitado: las claves y descargas del pedido. Un cliente invitado recibe el enlace del seguimiento en el correo.

Un enlace de descarga caducado o agotado muestra un mensaje claro que invita al cliente a contactarte.

Gestionar un pedido en el back office

En la página del pedido, el panel Claves de licencia y descargas muestra cada línea digital con sus claves, su validez, los dispositivos activados, las descargas y los cinco últimos accesos (fecha, IP).

• Entregar ahora / reintentar: procesa el pedido sea cual sea su estado. Útil para un pedido hecho antes de activar el producto, o si el empleado que cambió el estado no tiene permiso para ver el módulo (PrestaShop no ejecuta entonces los hooks del módulo).
• Reenviar el correo.
• Sustituir una clave: se revoca y se envía una clave nueva al cliente.
• Reiniciar las descargas: pone el contador a cero y prolonga el enlace con la validez del producto.
• Restablecer las activaciones de una clave.
• Revocar todo y Reactivar: la reactivación devuelve las claves revocadas con el pedido, no las sustituidas a mano.

Página Catálogo > Claves de licencia

Claves

La tabla Stock por producto da, para cada producto, las claves disponibles, entregadas y revocadas y las líneas en espera. Los productos con stock bajo aparecen resaltados. La lista de claves se filtra por producto, estado, clave exacta, referencia o ID de pedido y lote. Las claves están ocultas por defecto (botón de ojo para mostrarlas, botón de copiar). Acciones: revocar y sustituir, devolver al stock una clave revocada, eliminar una clave disponible o revocada, restablecer activaciones, exportación CSV de las claves filtradas.

Entregas

Todas las líneas entregadas o en espera, primero las que esperan, filtrables por estado, referencia o ID de pedido o correo del cliente. Acciones: reintentar, reenviar, reiniciar las descargas.

API de licencias

Activa Activar la API de licencias en los ajustes. La página de configuración muestra la dirección de la API, un ejemplo curl y la lista de códigos de error.

Punto de acceso: https://tu-tienda.com/module/dflicensekeys/api (POST o GET). Parámetros:

• action: validate, activate o deactivate.
• license_key: la clave introducida por el cliente.
• instance: identificador único del dispositivo, dominio o instalación, obligatorio para activate y deactivate.
• label: nombre legible opcional mostrado al cliente («PC de la oficina»).
• product_id: opcional, limita la comprobación a un producto.
• secret: obligatorio solo si Exigir el secreto de la API está activado. Actívalo cuando solo tu servidor llama a la API, no cuando el software la llama desde el equipo del cliente.

La respuesta JSON contiene success, error y un objeto license: status (active, revoked, expired), product_id, product_name, purchased_at, expires_at, max_activations, activations, activated.

curl -X POST "https://tu-tienda.com/module/dflicensekeys/api" 
  -d action=activate 
  -d license_key=ABCD-EFGH-JKLM-NPQR 
  -d instance=7f3c9a1e-equipo 
  -d label="PC de la oficina"

Códigos de error: 404 invalid_license (clave desconocida o aún no vendida), 403 license_revoked o license_expired, 403 activation_limit_reached, 400 missing_instance o unknown_action, 401 invalid_secret, 429 too_many_failed_attempts (más de 30 fallos por hora desde la misma IP).

RGPD y hooks para desarrolladores

Con el módulo oficial psgdpr, la exportación de los datos de un cliente incluye sus claves, sus fechas, las descargas y los dispositivos activados. Al eliminar un cliente se anonimizan sus entregas y activaciones y se borra el registro de descargas: las claves siguen siendo válidas, porque se pagaron.

Dos hooks permiten conectar un CRM o un servidor de licencias externo:

• actionDfLicenseKeysDelivered: id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (claves en claro).
• actionDfLicenseKeysRevoked: id_order.

Solución de problemas

El cliente no ha recibido sus claves

Comprueba que el estado del pedido figura en Entregar cuando el pedido pase a y haz clic en Entregar ahora / reintentar en el pedido. Si el panel muestra claves entregadas, haz clic en Reenviar el correo y revisa la configuración de correo de PrestaShop.

Los pedidos se quedan «A la espera de claves»

El stock del producto (o de la combinación) está vacío. Importa claves: los pedidos en espera salen automáticamente. Comprueba que la opción por combinación corresponde a la combinación en la que importas.

Las claves aparecen como «[?]» con un aviso rojo

La clave cookie de la tienda o el ajuste DFLK_SECRET ha cambiado, a menudo tras una migración. Restaura el archivo parameters.php anterior.

El enlace de descarga indica que el archivo no está disponible

El archivo se ha quitado de la ficha o se ha borrado de la carpeta /download/. Vuelve a subirlo desde la pestaña Módulos del producto.

La cantidad del producto es negativa

Hay pedidos que esperan más claves de las que contiene el stock. Importa claves y la cantidad sube sola.

Compatibilidad

• PrestaShop 8.0 a 9.x, el mismo ZIP cubre ambas ramas, con la ficha de producto antigua y la nueva.
• Arquitectura ModuleAdminController, sin dependencia de Composer, PHP 7.2 o superior, extensión openssl.
• Interfaz y correos en francés, inglés, español, alemán, italiano, neerlandés, polaco y portugués.