Levantamento em loja (Store Pickup): guia completo
Instalar, configurar e explorar o levantamento em loja: transportadora dedicada, escolha do ponto de levantamento num mapa interativo (Leaflet/OpenStreetMap, sem chave de API), gestão das lojas e seguimento da encomenda para PrestaShop 8 e 9.
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
- Comprima a pasta
datafireflystorepickup(o arquivo tem de conter a própria pasta, não apenas o seu conteúdo). - No back-office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e coloque o arquivo ZIP.
- 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.displayOrderConfirmationedisplayOrderDetail: 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 peloObjectModelDataFireflyPickupStore.datafirefly_pickup_selection: a loja escolhida por carrinho (chaveid_cart), antes da validação da encomenda.datafirefly_pickup_order: o instantâneo da loja por encomenda (chaveid_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.