# DataFirefly Subscriptions: guia completo (PrestaShop 8 e 9) > Apresentação O DataFirefly Subscriptions transforma a sua loja PrestaShop 8 ou 9 numa máquina de receitas recorrentes. O módulo assenta numa arquitetura «card on file»: o cliente paga uma única… - Página: - Idioma: pt - Atualizado em: 2026-09-02 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-subscriptions/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-subscriptions/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-subscriptions/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-subscriptions/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-subscriptions/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-subscriptions/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-subscriptions/index.md) - Índice: ## Apresentação O DataFirefly Subscriptions transforma a sua loja PrestaShop 8 ou 9 numa máquina de receitas recorrentes. O módulo assenta numa arquitetura **«card on file»**: o cliente paga uma única vez no checkout através de uma opção de pagamento nativa, o seu cartão é registado de forma segura no Stripe, e depois um cron diário debita automaticamente o cartão a cada vencimento e cria uma **verdadeira encomenda PrestaShop** no montante exato, portes incluídos. Pontos-chave da arquitetura: - **Um único motor de faturação**: nenhum objeto Subscription do lado do Stripe, tudo é comandado pela sua loja. Os débitos duplos são estruturalmente impossíveis. - **Montantes exatos**: cada renovação reconstrói um carrinho real e calcula o total através do motor de preços do PrestaShop (descontos, impostos, portes). - **3DS/SCA gerido**: a autenticação forte é gerida no pagamento inicial; as renovações usam o mecanismo off-session conforme à SCA. - **Nenhum dado bancário do lado do PrestaShop**: a conformidade PCI-DSS é assegurada pelo Stripe. **Adaptação para Portugal:** os e-mails do módulo (confirmação de renovação, lembrete de pagamento falhado, resiliação) são fornecidos em francês e inglês; crie a pasta `mails/pt/` a partir da versão inglesa antes de ativar as subscrições. Sobre a permanência mínima dos planos: o Decreto-Lei n.º 24/2014 garante ao consumidor 14 dias de livre resolução após a primeira encomenda, e as cláusulas de fidelização devem ser claramente apresentadas antes da adesão; verifique as suas condições gerais com um consultor jurídico. ## Instalação 1. Transfira o ZIP do módulo a partir da sua conta de cliente DataFirefly. 2. No seu back-office PrestaShop: **Módulos → Gestor de módulos → Instalar um módulo**, e selecione o ZIP. 3. O módulo cria automaticamente as suas tabelas, os seus separadores de administração (Subscrições, Planos, Registos, Painel) e regista os seus hooks. 4. Clique em **Configurar** para abrir a página de configuração. **Pré-requisitos:** PrestaShop 8.0 a 9.x, PHP 8.0 a 8.4, uma conta Stripe (gratuita) e a possibilidade de criar uma tarefa cron no seu alojamento. Não é necessária nenhuma dependência Composer. **Atualização a partir de uma versão 1.x:** instale simplesmente o novo ZIP por cima. Os scripts de migração são executados automaticamente e registam nomeadamente as restrições de moedas/países/transportadoras necessárias à apresentação da opção de pagamento no checkout. ## Configuração Stripe ### Chaves API Na configuração do módulo, preencha as suas chaves Stripe. O módulo gere dois conjuntos de chaves distintos: - **Modo de teste**: chave pública `pk_test_...` e chave secreta `sk_test_...`, para validar o percurso completo sem débito real (cartão de teste `4242 4242 4242 4242`). - **Modo live**: chave pública `pk_live_...` e chave secreta `sk_live_...`, para a produção. Encontra estas chaves no seu painel Stripe: **Programadores → Chaves API**. Alterne entre teste e live com o interruptor «Modo» do módulo. ### Webhook O webhook serve apenas para os eventos excecionais (a faturação é comandada pelo cron, não pelo Stripe). No seu painel Stripe: **Programadores → Webhooks → Adicionar um endpoint**, com o URL apresentado na configuração do módulo (no formato `https://asualoja.pt/module/dfsubscription/webhook`), e subscreva estes três eventos: - `payment_method.detached`: cartão eliminado do lado do Stripe: a subscrição passa a «pagamento falhado» para o avisar antes do vencimento. - `charge.dispute.created`: litígio (chargeback): registado na subscrição em causa. - `charge.refunded`: reembolso: registado na subscrição em causa. Copie depois o **segredo de assinatura** (`whsec_...`) fornecido pelo Stripe para o campo correspondente da configuração. **Importante:** em modo live, os pedidos de webhook não assinados são recusados. Preencha obrigatoriamente o segredo de assinatura antes de passar a produção. ## Configuração do cron O cron é o motor das renovações: deteta todos os dias as subscrições que chegaram ao vencimento, debita os cartões registados e cria as encomendas. O URL protegido por token é apresentado na configuração e no painel do módulo, no formato: ``` https://asualoja.pt/module/dfsubscription/cron?token=O_SEU_TOKEN ``` Crie uma tarefa cron diária no seu alojamento (cPanel, Plesk, crontab) que chame este URL. Exemplo de crontab para uma execução todos os dias às 6h00: ``` 0 6 * * * curl -s "https://asualoja.pt/module/dfsubscription/cron?token=O_SEU_TOKEN" > /dev/null 2>&1 ``` Uma execução diária é suficiente: o módulo trata numa só passagem todas as subscrições vencidas, com um limite de tempo alargado para os grandes volumes. Pode também usar um serviço externo como o cron-job.org se o seu alojamento não propuser cron. ## Criar planos de subscrição Os planos são geridos diretamente a partir da página de produto do back-office: **Catálogo → Produtos → o seu produto → separador Módulos / DataFirefly Subscriptions**. Para cada plano, defina: - **Frequência de faturação**: semanal, quinzenal, mensal, trimestral, semestral ou anual. - **Frequência de entrega**: idêntica à faturação, semanal, quinzenal ou mensal. Exemplo: faturação mensal + entrega semanal = box semanal com pagamento mensal. - **Desconto (%)**: a redução concedida aos subscritores em relação ao preço de compra única. É apresentado na página de produto e aplica-se também a cada renovação. - **Permanência mínima**: número de ciclos antes de a resiliação ser possível (0 = resiliação livre). - **Ciclos máximos**: para subscrições de duração limitada (0 = ilimitado). - **Dias de teste**: período de experiência antes da primeira faturação. Um produto pode propor vários planos (ex.: mensal -10% e anual -20%): o cliente escolhe no bloco «Subscreva e poupe» da página de produto. ## Percurso do cliente ### Página de produto Um bloco expansível apresenta os planos disponíveis com os seus preços com desconto. O cliente seleciona o seu plano (a seleção é registada na base de dados, fiável mesmo que mude de dispositivo), e adiciona depois ao carrinho normalmente. ### Checkout e pagamento Na etapa de pagamento, a opção **«Pagar com cartão e ativar a minha subscrição»** aparece se o carrinho contiver apenas produtos em subscrição e o cliente tiver sessão iniciada. O formulário de cartão seguro do Stripe é apresentado diretamente na página: 1. O cliente introduz o seu cartão; o 3D Secure dispara automaticamente se o seu banco o exigir. 2. O pagamento cobre o **total exato do carrinho**, portes incluídos. 3. O cartão é registado no Stripe para os ciclos seguintes (card on file, com consentimento conforme à SCA). 4. O módulo volta a verificar do lado do servidor o estado e o montante do pagamento antes de criar a encomenda: nunca se confia apenas na palavra do navegador. Os carrinhos mistos (subscrição + produto clássico) são bloqueados do lado do cliente e do lado do servidor: o cliente é convidado a finalizar separadamente. É isso que garante montantes de renovação sempre coerentes. ## Renovações A cada execução do cron, para cada subscrição que chegou ao vencimento: 1. O módulo reconstrói um **verdadeiro carrinho PrestaShop**: produto, combinação, morada e transportadora de origem. 2. O desconto do plano é aplicado através de uma regra de carrinho automática de uso único. 3. O total exato é calculado pelo motor de preços nativo: impostos e portes incluídos se a opção «Portes nas renovações» estiver ativa (está por defeito). 4. O cartão registado é debitado fora de sessão precisamente por esse montante. 5. É criada uma encomenda PrestaShop padrão, com o estado de encomenda à sua escolha (configurável, ex.: um estado dedicado «Renovação»). 6. O cliente recebe o e-mail de confirmação de renovação; o evento é registado. Cada encomenda de renovação é visível em **Encomendas** como qualquer venda, com a sua transação Stripe associada: as suas exportações contabilísticas e a sua gestão de stock funcionam sem alteração. ## Dunning: gestão das falhas de pagamento Quando um débito de renovação falha (cartão expirado, plafond, recusa bancária): 1. A subscrição passa ao estado **«pagamento falhado»** e o cliente recebe imediatamente um e-mail de lembrete a convidá-lo a atualizar o seu cartão. 2. O cron tenta de novo automaticamente o pagamento: por defeito **3 tentativas com 3 dias de intervalo**, sendo os dois valores configuráveis. 3. Após o número de falhas consecutivas configurado, a subscrição é anulada automaticamente e o cliente é informado. Cada tentativa e o seu resultado são registados nos logs da subscrição. Na prática, o dunning recupera 50 a 70% dos pagamentos que teriam sido perdidos numa falha seca. ## Área de cliente «As minhas subscrições» Acessível a partir da conta de cliente, esta área lista as subscrições com o seu estado, a próxima data de faturação e de entrega. Consoante as suas definições, o cliente pode: - **Colocar em pausa / retomar**: as datas são recalculadas na retoma. - **Saltar o próximo ciclo**: a faturação e a entrega são adiadas em conjunto por um período. - **Resiliar**: livremente, ou apenas após a permanência mínima do plano. Na resiliação, o cartão registado é automaticamente desassociado no Stripe e é enviado um e-mail de confirmação. Cada ação pede uma confirmação e segue o padrão POST-redirect-GET: nenhuma submissão dupla possível, mensagens de confirmação nativas do PrestaShop. ## Back-office - **Painel**: MRR, subscrições ativas, taxa de churn, pagamentos falhados, URL de cron e de webhook prontos a copiar. - **Subscrições**: lista filtrável por estado, frequência e cliente; vista detalhada com o histórico das encomendas geradas e os registos, e ligações diretas para a encomenda e a ficha de cliente. - **Planos**: vista geral de todos os planos existentes (a criação é feita a partir da página de produto). - **Registos**: todos os eventos com carimbo temporal: criações, renovações, falhas, lembretes, pausas, resiliações, webhooks recebidos. ## FAQ técnica e resolução de problemas ### A opção de pagamento não aparece no checkout - Verifique que o carrinho contém **apenas** produtos com um plano selecionado e que o cliente tem sessão iniciada. - Verifique que as chaves Stripe do modo ativo estão preenchidas. - Se acabou de migrar a partir de uma versão 1.x: reinstale o módulo ou relance a atualização: as restrições de moedas/países/transportadoras são acrescentadas pelos scripts de migração 2.x e são indispensáveis à apresentação da opção. ### As renovações não disparam - Verifique que a tarefa cron está agendada e que o seu URL contém o token correto (teste o URL num navegador: deve responder com um resumo JSON). - Consulte o separador Registos: cada execução do cron deixa aí um rasto. ### Um pagamento 3DS fica «pendente» Se o cliente fechar a página durante a autenticação 3D Secure, não ocorre nenhum débito e não é criada nenhuma encomenda. Pode simplesmente voltar a encomendar; o pagamento anterior expirará por si só do lado do Stripe. ### Como testar o percurso completo? 1. Passe o módulo para modo de teste e preencha as chaves `pk_test`/`sk_test`. 2. Crie um plano num produto, faça uma encomenda com o cartão `4242 4242 4242 4242` (ou `4000 0027 6000 3184` para forçar um desafio 3DS). 3. Na base de dados, avance a data `next_billing_date` da subscrição para ontem, e chame depois o URL de cron: deve aparecer uma encomenda de renovação. 4. Para testar o dunning, use o cartão `4000 0000 0000 0341` (falha no débito off-session). Precisa de ajuda? Abra um ticket a partir da sua conta de cliente DataFirefly: resposta em 24h úteis, em francês ou em inglês.