Chaves de licença e produtos digitais: documentação DataFirefly License Keys

Instalação

Instale o módulo em Módulos > Gestor de módulos > Enviar um módulo com o ficheiro ZIP, ou copie a pasta dflicensekeys para o diretório /modules/ da loja e clique em Instalar. É necessária a extensão PHP openssl.

Na instalação, o módulo cria as suas tabelas, regista os seus hooks e acrescenta o menu Catálogo > Chaves de licença. Gera também um segredo de cifragem próprio da loja.

A desinstalação conserva as chaves, as entregas e o segredo, para que repor o módulo não esvazie o seu stock. Ative Eliminar todas as chaves, entregas e ficheiros ao desinstalar apenas se quiser apagar tudo.

Definições do módulo

Entrega

• Entregar quando a encomenda passar a: os estados marcados como pagos (Pagamento aceite, Pagamento remoto aceite, Enviada, Entregue…) são selecionados na instalação. A passagem para um deles desencadeia a entrega. O processamento é idempotente: voltar a passar por um destes estados não envia chaves novas.
• Mostrar o aviso de entrega imediata nas páginas de produto: pequena caixa abaixo do preço dos produtos digitais.
• Enviar uma cópia dos e-mails de entrega para o endereço de alerta: cópia oculta para o primeiro endereço de alerta.

Cancelamentos e reembolsos

Com a revogação automática ativa, uma encomenda que passa a Cancelada ou Reembolsada (estados predefinidos) tem as chaves revogadas e as transferências bloqueadas. As chaves revogadas nunca voltam sozinhas ao stock.

Stock de chaves

• Sincronizar a quantidade do produto com as chaves disponíveis: a quantidade do PrestaShop passa a ser o número de chaves realmente livres, ou seja, as disponíveis menos as reservadas por encomendas ainda não entregues (uma transferência pendente, por exemplo) e menos as chaves em falta nas encomendas em espera. Com várias chaves por unidade, a quantidade é dividida em conformidade.
• Limite de alerta de stock baixo (5 por predefinição) e Endereço(s) de e-mail de alerta: é enviado um alerta quando as chaves disponíveis descem até esse limite ou uma encomenda aguarda chaves, no máximo uma vez por dia e por produto.

Valores predefinidos dos novos produtos digitais

Limite de transferências (5 por predefinição, 0 = ilimitado) e Validade do link em dias (0 = sem validade), aplicados ao ativar um produto.

API de licenças e ativações

Consulte a secção API mais abaixo. A opção Permitir que os clientes libertem ativações na sua conta está ativa por predefinição.

Configurar um produto digital

Abra a página do produto, separador Módulos, bloco Entrega digital e chaves de licença. O bloco é guardado com o seu próprio botão Guardar as definições digitais, independentemente do formulário do produto. Enquanto não clicar, é mostrado «Alterações não guardadas».

Defina o produto como Produto virtual para que não seja pedido envio no pagamento. O bloco lembra-o se não for o caso.

Chaves de licença

• Origem das chaves: apenas stock importado; stock importado e, quando esgotado, geração automática; sempre geradas automaticamente.
• Padrão de chave: usado pelo gerador. X = letra ou algarismo, A = letra, 9 = algarismo, os outros caracteres mantêm-se. Pelo menos 8 caracteres aleatórios, no máximo 128. Os caracteres ambíguos (0, O, 1, I) nunca são usados.
• Validade da licença (dias): 0 = licença vitalícia. A data de fim é calculada na entrega de cada chave.
• Máximo de ativações por chave: 0 = ilimitado. Controlado pela API de licenças.
• Chaves por unidade encomendada: 5 para um pacote de 5 licenças, por exemplo.
• Limite de alerta de stock baixo: deixe vazio para usar a definição global.
• Gerir um stock de chaves distinto para cada combinação: útil para «1 ano» e «3 anos», ou «Windows» e «Mac».

Ficheiro para transferir

Envie o ficheiro (instalador, PDF, arquivo). É guardado na pasta /download/ do PrestaShop com um nome aleatório e nunca fica acessível diretamente. Defina o limite de transferências por linha de encomenda e a validade do link. Substituir o ficheiro beneficia também os clientes já servidos.

Instruções de ativação

Texto opcional por idioma, apresentado com as chaves no e-mail e na conta do cliente. Um ponto verde assinala os idiomas preenchidos.

Importar e gerar chaves

A partir da página do produto (bloco Adicionar chaves ao stock) ou em Catálogo > Chaves de licença > Importar chaves:

• Cole as chaves, uma por linha, ou escolha um ficheiro TXT (uma chave por linha) ou CSV (chaves na primeira coluna, separador ;, , ou tabulação). Assinale A primeira linha do ficheiro é um cabeçalho se necessário.
• Para um produto gerido por combinação, escolha a combinação.
• O nome do lote (fatura do fornecedor, por exemplo) permite encontrar ou exportar estas chaves mais tarde.

Os duplicados, já em stock para este produto ou repetidos na lista, são ignorados. As chaves com mais de 1000 caracteres são rejeitadas. Um produto ainda não configurado é ativado com as definições predefinidas. As encomendas à espera de chaves são entregues logo após a importação, as mais antigas primeiro.

Para gerar um lote no stock (até 10 000 chaves), indique o número e o padrão e clique em Gerar. Útil para alimentar o seu próprio sistema de licenças ou um revendedor através da exportação CSV.

O que o cliente recebe

• E-mail de entrega no idioma da encomenda: chaves, validade, botão de transferência com o número restante, instruções de ativação. É enviado um novo e-mail sempre que são atribuídas chaves novas (entrega diferida ou substituição).
• Página de confirmação da encomenda: as chaves aparecem logo se o pagamento for imediato; caso contrário, uma mensagem indica que serão enviadas após a confirmação do pagamento.
• A minha conta > As minhas chaves de licença: todas as chaves de todas as encomendas, com botão de copiar, links de transferência, validade e dispositivos ativados. O link só aparece para os clientes que receberam pelo menos uma entrega.
• Detalhe da encomenda e acompanhamento de convidado: as chaves e transferências da encomenda. Um cliente convidado recebe o link de acompanhamento no e-mail.

Um link de transferência expirado ou esgotado mostra uma mensagem clara que convida o cliente a contactá-lo.

Gerir uma encomenda no back-office

Na página da encomenda, o painel Chaves de licença e transferências mostra cada linha digital com as suas chaves, a validade, os dispositivos ativados, as transferências e os cinco últimos acessos (data, IP).

• Entregar agora / tentar de novo: processa a encomenda seja qual for o estado. Útil para uma encomenda feita antes de ativar o produto, ou se o funcionário que mudou o estado não tem permissão para ver o módulo (o PrestaShop não executa então os hooks do módulo).
• Reenviar o e-mail.
• Substituir uma chave: é revogada e é enviada uma nova chave ao cliente.
• Repor transferências: põe o contador a zero e prolonga o link pela validade do produto.
• Repor ativações de uma chave.
• Revogar tudo e Reativar: a reativação devolve as chaves revogadas com a encomenda, não as substituídas manualmente.

Página Catálogo > Chaves de licença

Chaves

A tabela Stock por produto indica, para cada produto, as chaves disponíveis, entregues e revogadas e as linhas em espera. Os produtos com stock baixo ficam destacados. A lista de chaves filtra-se por produto, estado, chave exata, referência ou ID da encomenda e lote. As chaves ficam ocultas por predefinição (botão de olho para as mostrar, botão de copiar). Ações: revogar e substituir, repor em stock uma chave revogada, eliminar uma chave disponível ou revogada, repor ativações, exportação CSV das chaves filtradas.

Entregas

Todas as linhas entregues ou em espera, primeiro as que aguardam, filtráveis por estado, referência ou ID da encomenda ou e-mail do cliente. Ações: tentar de novo, reenviar, repor transferências.

API de licenças

Ative Ativar a API de licenças nas definições. A página de configuração mostra o endereço da API, um exemplo curl e a lista de códigos de erro.

Endpoint: https://a-sua-loja.pt/module/dflicensekeys/api (POST ou GET). Parâmetros:

• action: validate, activate ou deactivate.
• license_key: a chave introduzida pelo cliente.
• instance: identificador único do dispositivo, domínio ou instalação, obrigatório para activate e deactivate.
• label: nome legível opcional mostrado ao cliente («PC do escritório»).
• product_id: opcional, limita a verificação a um produto.
• secret: obrigatório apenas se Exigir o segredo da API estiver ativo. Ative-o quando só o seu servidor chama a API, não quando o software a chama a partir do computador do cliente.

A resposta JSON contém success, error e um objeto license: status (active, revoked, expired), product_id, product_name, purchased_at, expires_at, max_activations, activations, activated.

curl -X POST "https://a-sua-loja.pt/module/dflicensekeys/api" 
  -d action=activate 
  -d license_key=ABCD-EFGH-JKLM-NPQR 
  -d instance=7f3c9a1e-posto 
  -d label="PC do escritório"

Códigos de erro: 404 invalid_license (chave desconhecida ou ainda não vendida), 403 license_revoked ou license_expired, 403 activation_limit_reached, 400 missing_instance ou unknown_action, 401 invalid_secret, 429 too_many_failed_attempts (mais de 30 falhas por hora a partir do mesmo IP).

RGPD e hooks para programadores

Com o módulo oficial psgdpr, a exportação dos dados de um cliente inclui as suas chaves, as datas, as transferências e os dispositivos ativados. A eliminação de um cliente anonimiza as suas entregas e ativações e apaga o registo de transferências: as chaves continuam válidas, porque foram pagas.

Dois hooks permitem ligar um CRM ou um servidor de licenças externo:

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

Resolução de problemas

O cliente não recebeu as chaves

Verifique se o estado da encomenda está em Entregar quando a encomenda passar a e clique em Entregar agora / tentar de novo na encomenda. Se o painel mostrar chaves entregues, clique em Reenviar o e-mail e verifique a configuração de e-mail do PrestaShop.

As encomendas ficam «À espera de chaves»

O stock do produto (ou da combinação) está vazio. Importe chaves: as encomendas em espera seguem automaticamente. Verifique se a opção por combinação corresponde à combinação para onde importa.

As chaves aparecem como «[?]» com um aviso vermelho

A chave cookie da loja ou a definição DFLK_SECRET mudou, muitas vezes após uma migração. Reponha o ficheiro parameters.php anterior.

O link de transferência indica que o ficheiro não está disponível

O ficheiro foi retirado do produto ou apagado da pasta /download/. Volte a enviá-lo no separador Módulos do produto.

A quantidade do produto é negativa

Há encomendas à espera de mais chaves do que o stock contém. Importe chaves e a quantidade sobe sozinha.

Compatibilidade

• PrestaShop 8.0 a 9.x, o mesmo ZIP cobre os dois ramos, página de produto antiga e nova.
• Arquitetura ModuleAdminController, sem dependência Composer, PHP 7.2 ou superior, extensão openssl.
• Interface e e-mails em francês, inglês, espanhol, alemão, italiano, neerlandês, polaco e português.