# Módulo Ótica PrestaShop: instalação e configuração
> Apresentação O módulo dfopticlens permite vender óculos graduados no PrestaShop 8 e 9. Na página de uma armação, o cliente escolhe um tipo de lente, introduz a receita, escolhe uma…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-24
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfopticlens/index.md), [en](https://www.datafirefly.com/en/documentation/dfopticlens/index.md), [es](https://www.datafirefly.com/es/documentation/dfopticlens/index.md), [de](https://www.datafirefly.com/de/documentation/dfopticlens/index.md), [it](https://www.datafirefly.com/it/documentation/dfopticlens/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfopticlens/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfopticlens/index.md)
- Índice:
## Apresentação
O módulo **dfopticlens** permite vender óculos graduados no PrestaShop 8 e 9. Na página de uma armação, o cliente escolhe um tipo de lente, introduz a receita, escolhe uma lente entre os índices propostos, adiciona tratamentos e confirma um resumo. O servidor verifica cada valor, calcula o preço e confirma que a graduação pode ser montada na armação. O preço das lentes é somado à linha da armação através da personalização nativa do PrestaShop, e a receita acompanha a encomenda até à fatura.
## Instalação
1. Em _Módulos > Gestor de módulos_, clique em _Carregar um módulo_ e envie `dfopticlens-1.1.0.zip`.
2. A instalação cria o menu _Vender > Ótica_ com quatro páginas: Receitas, Armações, Lentes e índices, Tratamentos.
3. São criadas cinco lentes (1.50, 1.59 policarbonato, 1.60, 1.67, 1.74) e sete tratamentos com preços de exemplo. Ajuste-os antes de colocar online.
4. É criada a pasta `upload/dfopticlens/`, protegida por um ficheiro `.htaccess`: os ficheiros de receitas nunca ficam acessíveis pela web.
Atualização a partir da 1.0.0: carregue o ZIP 1.1.0 por cima. O script de atualização adiciona as novas definições e hooks sem perda de dados.
## Configuração do módulo
A página de configuração (botão _Configurar_ do módulo) agrupa as definições em três blocos.
### Introdução da receita
- **Convenção de cilindro enviada ao laboratório**: cilindro negativo, positivo ou mantido como escrito. O cliente introduz sempre os valores da sua receita; a transposição é feita ao guardar.
- **Envio do ficheiro da receita**: desativado, opcional ou obrigatório, com tamanho máximo em MB. Formatos aceites: PDF, JPG, PNG, verificados pelo conteúdo.
- **Avisar quando a receita tiver mais de** X anos (0 desativa).
- **Eliminar as receitas de carrinhos abandonados após** X dias.
- **Envio do ficheiro a partir da conta após a encomenda**: adiciona a página As minhas receitas à conta do cliente.
- **Opção Não sei a minha distância pupilar** e **distância pupilar média usada** (63 mm por defeito). A encomenda fica então assinalada a verificar.
### Regras de viabilidade
- **Bloquear as lentes que não podem ser fabricadas**: ativo por defeito. Desativado, a encomenda é aceite com um aviso.
- **Margem de biselagem** e **margem do diâmetro efetivo** quando o ED da armação é desconhecido (ED estimado = A + margem).
- **Altura mínima para progressivas** (28 mm) e **corredor curto abaixo de** (32 mm).
- Limiares de aviso: diferença entre os olhos, descentramento por olho, potência positiva em armações de fio nylon.
- **Espessura pretendida** da lente recomendada, **espessura central** das lentes negativas e **da borda** das positivas (furadas ou não).
### Preços
- **Preços introduzidos com IVA** ou sem IVA. Aplica-se às lentes a regra de imposto do produto armação.
- **Suplementos** de potência elevada e cilindro elevado: limiar em dioptrias e valor (0 desativa).
## Lentes e índices
Em _Vender > Ótica > Lentes e índices_, cada lente tem:
- um nome e uma descrição curta mostrados ao cliente, em cada idioma;
- o índice de refração, usado para estimar a espessura, e o material para a ficha de oficina;
- os tipos de lente para os quais é proposta e um preço por par para cada um: monofocal, progressiva, sem graduação;
- a esfera mínima e máxima e o cilindro máximo (valor absoluto, lidos em cilindro negativo como as gamas dos fabricantes);
- o maior diâmetro de lente em bruto disponível (0 desativa a verificação) e se pode ser furada para armações sem aro.
## Tratamentos
Em _Tratamentos_, cada tratamento tem um preço por par (0 mostra-o como incluído). O **grupo exclusivo** impede combinar dois tratamentos: os que têm o mesmo código, por exemplo `tint` para fotocromático, tinta solar e polarizado, excluem-se entre si. Também pode limitar um tratamento a certas lentes, por exemplo o polarizado aos índices 1.50 e 1.60.
## Armações
Uma armação liga um produto, ou uma das suas combinações, às suas medidas. O bloco das lentes só aparece nos produtos com uma armação ativada.
### Criar uma armação
1. Em _Armações_, clique em _Adicionar uma armação_, ou na página do produto, separador _Módulos_, em _Adicionar as medidas da armação_.
2. Procure o produto por nome, referência ou ID e escolha _Todas as combinações_ ou uma combinação concreta. Uma armação definida para uma combinação tem prioridade.
3. Indique o tipo (aro completo, fio nylon, sem aro), a largura da lente A, a ponte DBL e a altura da lente B, obrigatórias. São os números impressos na haste: 52□18 dá A = 52 e DBL = 18.
4. Opcional: o diâmetro efetivo ED (caso contrário é estimado) e a potência máxima aceite pela armação.
5. Marque os tipos de lente propostos e, se necessário, **Vender apenas com lentes**.
Com Vender apenas com lentes, o botão nativo do carrinho abre a escolha das lentes. Se uma chamada direta ao carrinho adicionar mesmo assim a armação sozinha, o módulo retira-a do carrinho.
### Importação e exportação CSV
O botão _Exportar CSV_ fornece um ficheiro no formato certo. A importação aceita ponto e vírgula ou vírgula e estas colunas:
```
product;combination;frame_type;lens_width;lens_height;bridge;ed;max_power;vision_types;lens_required;active
```
- `product`: ID ou referência do produto; `combination`: ID ou referência da combinação, vazio ou 0 para todas.
- `frame_type`: full, semi ou rimless; `vision_types`: single|progressive|plano.
- Uma armação existente (mesmo produto e combinação) é atualizada. As linhas recusadas são listadas com o seu número.
O botão _Ressincronizar produtos_ reconstrói os campos de personalização dos produtos, útil se um funcionário sem permissões no módulo alterou produtos.
## Percurso do cliente
1. **Tipo**: monofocal, progressiva ou sem graduação, conforme o que a armação propõe. Sem graduação, o passo da receita é saltado.
2. **Receita**: grelha OD / OE, distância pupilar em um ou dois valores, data, ficheiro e nota para o ótico. Um cliente com sessão iniciada pode reutilizar a receita de uma encomenda anterior.
3. **Lente**: cartões com preço por par, corte à escala, espessura estimada e lente recomendada. As lentes impossíveis ficam a cinzento com o motivo.
4. **Tratamentos**: os indisponíveis para a lente escolhida ficam a cinzento.
5. **Resumo**: estado de viabilidade, notas, detalhe do preço e total da armação e das lentes.
Os dados introduzidos mantêm-se se o cliente recarregar a página e são apagados após adicionar ao carrinho.
## Regras de viabilidade
| Verificação | Efeito |
| --- | --- |
| Esfera ou cilindro fora do intervalo da lente | Lente indisponível |
| Diâmetro em bruto necessário (ED + 2 × descentramento + margem) superior ao da lente | Lente indisponível se o bloqueio estiver ativo |
| Armação sem aro e material que não pode ser furado | Lente indisponível se o bloqueio estiver ativo |
| Altura B inferior ao mínimo para uma progressiva | Bloqueante (ou aviso) |
| Altura B abaixo do limiar de corredor curto | Informação |
| Potência superior ao máximo da armação | Bloqueante (ou aviso) |
| Diferença entre os olhos, forte descentramento, potência positiva elevada em fio nylon, receita antiga, distância pupilar desconhecida | Aviso, encomenda assinalada a verificar |
Os cálculos usam a forma em cilindro negativo. A espessura é estimada com a fórmula da flecha: serve para comparar índices, não é o cálculo do laboratório.
## Preços, descontos e fatura
O preço das lentes é guardado sem IVA na personalização da linha do carrinho. O PrestaShop soma-o ao preço da armação e aplica o IVA do produto. Se a armação tiver uma redução em percentagem (preço específico ou grupo de clientes), o PrestaShop aplica-a também às lentes: o painel mostra o preço riscado e uma linha Promoção da armação aplicada também às lentes, para que o total anunciado corresponda ao carrinho.
## Encomendas e ficha de oficina
- A página da encomenda no back-office mostra um bloco por receita: valores transpostos, lente, tratamentos, medidas da armação, descentramento e lente em bruto mínima por olho, notas de viabilidade e detalhe do preço.
- **Imprimir a ficha de oficina** abre uma página A4 pronta a imprimir.
- **Descarregar o ficheiro da receita** obtém a digitalização enviada pelo cliente.
- _Vender > Ótica > Receitas_ lista todas as receitas com o seu estado: OK, a verificar, inviável.
## Conta do cliente: As minhas receitas
Um cliente que encomendou lentes vê a ligação _As minhas receitas_ na sua conta. A página mostra cada receita com a encomenda associada. Se o envio do ficheiro for opcional e o cliente não o tiver anexado, pode enviá-lo a partir desta página; o ótico encontra-o depois na encomenda.
## Dados de saúde e RGPD
- Os ficheiros de receitas ficam fora da pasta pública e só se descarregam a partir do back-office.
- As receitas de carrinhos nunca encomendados são eliminadas após o prazo definido, juntamente com a linha de carrinho correspondente.
- Com o módulo oficial psgdpr, a exportação e eliminação dos dados de um cliente incluem as suas receitas.
## Resolução de problemas
### O bloco das lentes não aparece na página do produto
Verifique se o produto tem uma armação ativada e se o tema mostra o hook `displayProductAdditionalInfo`. Limpe a cache do PrestaShop.
### O botão nativo do carrinho não abre o painel numa armação apenas com lentes
O módulo interceta os botões com `data-button-action="add-to-cart"`. Se o seu tema usar outro atributo, o bloqueio do lado do servidor continua ativo: a armação sozinha é retirada do carrinho.
### O total do painel é diferente do carrinho
Uma redução de valor fixo só se aplica à armação e uma regra de carrinho (cupão) aplica-se ao carrinho inteiro: não aparecem no painel das lentes.