# Levantamento em loja (Store Pickup): guia completo

> Apresentação O módulo Levantamento em Loja (datafireflystorepickup) permite aos seus clientes irem buscar a encomenda a um dos seus pontos de venda, em vez de a receberem em casa. Na…

- Página: <https://www.datafirefly.com/pt/documentation/datafireflystorepickup/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafireflystorepickup/index.md), [en](https://www.datafirefly.com/en/documentation/datafireflystorepickup/index.md), [es](https://www.datafirefly.com/es/documentation/datafireflystorepickup/index.md), [de](https://www.datafirefly.com/de/documentation/datafireflystorepickup/index.md), [it](https://www.datafirefly.com/it/documentation/datafireflystorepickup/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafireflystorepickup/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafireflystorepickup/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Apresentação

O módulo **Levantamento em Loja** (`datafireflystorepickup`) permite aos seus clientes irem buscar a encomenda a um dos seus pontos de venda, em vez de a receberem em casa. Na instalação, é criada automaticamente uma transportadora «Levantamento em loja». No checkout, quando o cliente escolhe essa transportadora, aparecem uma lista de lojas e um mapa interativo: ele seleciona o seu ponto de levantamento e essa escolha fica registada com a encomenda.

O mapa assenta no **Leaflet** e no **OpenStreetMap**, sem qualquer chave de API a fornecer. O módulo é compatível com PrestaShop 8.x e 9.x e apoia-se exclusivamente nos hooks nativos, sem overrides do núcleo.

## Instalação

1. Comprima a pasta `datafireflystorepickup` (o arquivo tem de conter a própria pasta, não apenas o seu conteúdo).
2. No back-office, abra **Módulos > Gestor de módulos**, clique em **Carregar um módulo** e coloque o arquivo ZIP.
3. Terminada a instalação, clique em **Configurar**.

Na instalação, o módulo executa automaticamente as operações seguintes: criação da transportadora «Levantamento em loja» (com os seus intervalos de preço e de peso, todas as zonas e todos os grupos de clientes), criação das tabelas de dados, registo dos hooks e inicialização dos custos de levantamento a 0.

A transportadora é seguida pela sua **referência** (`id_reference`) e não apenas pelo identificador: pode alterá-la livremente em **Transporte > Transportadoras** (nome, prazo, logótipo, zonas) sem quebrar a ligação com o módulo.

## Configuração

Vá a **Módulos > Levantamento em loja > Configurar**. A página reúne as definições gerais e a gestão das lojas.

### Custos de levantamento

O campo **Custos de levantamento (sem IVA)** define o custo aplicado à transportadora de levantamento. Deixe **0** para um levantamento gratuito, ou introduza um valor sem imposto. Este preço aplica-se seja qual for a loja escolhida.

### Gestão das lojas

A lista de lojas mostra todos os seus pontos de levantamento com o nome, morada, código postal, localidade, telefone e estado. A partir dela, pode acrescentar, alterar, ativar, desativar ou eliminar uma loja.

Cada loja tem os campos seguintes:

- **Nome** (obrigatório): designação apresentada ao cliente.
- **Morada** (obrigatória) e **Código postal**.
- **Localidade** (obrigatória).
- **Telefone**.
- **Horário**: campo livre, por exemplo «Seg-Sáb 9h-19h».
- **Latitude** e **Longitude** (obrigatórias): posição da loja no mapa.
- **Ativa**: só as lojas ativas são propostas no checkout.

Para preencher as coordenadas, não é preciso procurá-las manualmente: **clique no mapa** apresentado por baixo do formulário para colocar o ponto, ou use a geocodificação da morada. A latitude e a longitude preenchem-se automaticamente. A geocodificação assenta no **Nominatim / OpenStreetMap**.

O código postal português tem o formato 0000-000. Introduza-o por extenso no campo, tal como aparece nas suas moradas: o campo é livre e não impõe qualquer máscara. Se o Nominatim não encontrar a morada com o código postal completo, tente com a rua e a localidade e ajuste depois o ponto diretamente no mapa.

## Do lado do cliente (checkout)

No passo de entrega, quando o cliente seleciona a transportadora «Levantamento em loja», o módulo apresenta por baixo dela a **lista das lojas ativas** e um **mapa interativo** onde cada loja é assinalada por um marcador. O cliente escolhe o seu ponto de levantamento na lista ou diretamente no mapa.

A seleção é **obrigatória**: enquanto não for escolhida uma loja, o passo de entrega não pode ser validado e uma mensagem convida o cliente a selecionar a sua loja. A escolha é gravada em tempo real (através de um pedido AJAX) e associada ao carrinho.

Se não houver qualquer loja ativa disponível, aparece uma mensagem de aviso no lugar do mapa.

As cadeias do módulo são fornecidas em francês, inglês, espanhol, alemão e italiano, sem português. Como a lista de lojas e as mensagens do checkout são vistas pelo cliente, traduza-as em **Internacional > Traduções** antes de ativar a transportadora.

## Seguimento da encomenda

Depois de a encomenda ser validada, a loja escolhida é guardada como um **instantâneo** associado à encomenda (nome, morada, código postal, localidade, telefone e horário no momento da compra). Assim, continua consultável mesmo que a loja seja alterada ou eliminada posteriormente. O ponto de levantamento aparece automaticamente:

- na **página de confirmação da encomenda**;
- no **detalhe da encomenda** da área de cliente;
- na **ficha da encomenda no back-office**, na coluna lateral.

O levantamento em loja é uma entrega, não uma venda ao balcão: a fatura continua a ser emitida pelo seu software de faturação certificado pela AT, com as mesmas obrigações. Se emite documento de transporte, tenha em conta que a mercadoria circula do seu armazém para o ponto de levantamento, e não para a morada do cliente.

## Estrutura técnica

Esta secção destina-se a integradores e programadores que queiram compreender o funcionamento interno do módulo.

### Tipo de módulo

A classe principal `DataFireflyStorePickup` estende `CarrierModule`. O preço da transportadora é devolvido por `getOrderShippingCost()` e `getOrderShippingCostExternal()`, ambos baseados na configuração `DATAFIREFLY_PICKUP_FEE`.

### Hooks utilizados

- `actionFrontControllerSetMedia`: carrega o Leaflet (CSS e JS remotos) e os recursos de front do módulo na página de encomenda.
- `displayCarrierExtraContent`: injeta a lista e o mapa por baixo da transportadora de levantamento.
- `actionCarrierUpdate`: atualiza o identificador da transportadora quando esta é alterada no back-office.
- `actionValidateStepComplete`: torna obrigatória a seleção da loja no passo de entrega.
- `actionValidateOrder`: fixa a loja escolhida na encomenda.
- `displayOrderConfirmation` e `displayOrderDetail`: apresentam o ponto de levantamento do lado do cliente.
- `displayAdminOrderSide`: apresenta o ponto de levantamento na ficha da encomenda do back-office.

### Reconhecimento da transportadora

O método `isPickupCarrier()` identifica a transportadora de levantamento tanto pela referência (`id_reference`) como pelo identificador atual, porque o ID de uma transportadora do PrestaShop muda a cada alteração no back-office. São guardadas duas chaves de configuração para o efeito: `DATAFIREFLY_PICKUP_CARRIER_ID` e `DATAFIREFLY_PICKUP_CARRIER_REF`.

### Tabelas de dados

- `datafirefly_pickup_store`: as lojas (nome, morada, coordenadas, horário, estado). Gerida pelo `ObjectModel` `DataFireflyPickupStore`.
- `datafirefly_pickup_selection`: a loja escolhida por carrinho (chave `id_cart`), antes da validação da encomenda.
- `datafirefly_pickup_order`: o instantâneo da loja por encomenda (chave `id_order`), conservado depois da compra.

### Seleção por AJAX

O controlador de front `ajax` (ação `selectStore`) grava a loja selecionada em `datafirefly_pickup_selection` para o carrinho atual. Na validação da encomenda, essa seleção é copiada para `datafirefly_pickup_order` e a linha do carrinho é eliminada.

## Desinstalação

A desinstalação marca a transportadora como eliminada e desativada, retira as chaves de configuração (`DATAFIREFLY_PICKUP_CARRIER_ID`, `DATAFIREFLY_PICKUP_CARRIER_REF`, `DATAFIREFLY_PICKUP_FEE`) e elimina as três tabelas do módulo. As lojas registadas são, portanto, apagadas.

## Limitações conhecidas

- O ponto de levantamento não é injetado nos e-mails de confirmação: continua visível no back-office e na área de cliente.
- A geocodificação assenta no Nominatim (OpenStreetMap), pelo que se recomenda uma utilização moderada, para respeitar as condições de utilização do serviço.

## Perguntas frequentes

### É precisa uma chave de API para o mapa?

Não. O mapa usa o Leaflet e os mosaicos do OpenStreetMap, sem chave de API nem configuração externa.

### O cliente pode validar a encomenda sem escolher uma loja?

Não. Quando a transportadora de levantamento está selecionada, a escolha de uma loja é obrigatória para passar o passo de entrega.

### O que acontece ao ponto de levantamento se eliminar uma loja depois de uma encomenda?

A encomenda conserva um instantâneo da loja (nome, morada, horário) gravado no momento da compra. Continua consultável mesmo depois de a loja ser eliminada.

### O módulo é compatível com o PrestaShop 9?

Sim, o módulo é compatível com PrestaShop 8.x e 9.x.