VibeFox DPD Pickup for PrestaShop — Ajuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Credenciais da DPD Baltic (Lituânia, Letônia, Estônia): a lista de pontos de retirada vem do serviço web da DPD Baltic. Você precisa do nome de usuário e da senha da API que a DPD fornece aos seus clientes empresariais. Peça-os ao seu gerente de conta da DPD ou ao atendimento ao cliente da DPD do seu país. Uma conta lista os pontos de retirada da Lituânia, Letônia e Estônia.
DPD Eslováquia: a busca pública de parcelshops da DPD Eslováquia não exige credenciais.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre depois VibeFox DPD Pickup na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Escolha a sua API da DPD. Para DPD Lituânia, Letônia ou Estônia, informe o nome de usuário e a senha da API. Confira os valores por país e clique em Save. Depois clique em Refresh pickup points para testar a conexão (veja Configuração).
Na instalação, o módulo cria a transportadora DPD Pickup Point com o texto de prazo de entrega DPD Pickup point or locker. A transportadora é atribuída às zonas da Eslováquia, Lituânia, Letônia e Estônia e a todos os grupos de clientes, sem regra de imposto. Você pode alterar zonas, grupos de clientes, texto de prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox DPD Pickup > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as listas de pontos de retirada em cache.
Avisos no topo da página informam quando o nome de usuário ou a senha da DPD Baltic estão vazios, quando nenhum valor foi definido (nos dois casos a transportadora não aparece na finalização de compra), quando a transportadora foi excluída e quando a unidade de peso da loja (International > Localization, Local units) não é reconhecida pelo módulo, de modo que os pesos dos produtos são lidos em kg. Um valor que não é número, ou um número negativo, em um campo de valor ou peso não é salvo: o campo fica vazio e um aviso o indica. As linhas de Country prices que não estão no formato CC:VALOR são listadas em um aviso e ignoradas.
Geral
Enable/Disable: ativa ou desativa a DPD Pickup. É a mesma chave do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado ao cliente na finalização de compra. Padrão: DPD Pickup Point. Obrigatório, no máximo 64 caracteres.
Tax status: a regra de imposto da transportadora aplicada ao valor do frete. None significa sem imposto. As outras opções mostram Taxable com o nome de uma regra de imposto da sua loja.
Lista de pontos de retirada da DPD
Os pontos de retirada são carregados da DPD e ficam em cache por 24 horas.
DPD API: a empresa DPD com a qual você tem sua conta. As contas Baltic usam o serviço web do próprio país.
API username (Baltic): seu nome de usuário do serviço web da DPD Baltic. Não é necessário para a DPD Eslováquia. Limpar esse campo também apaga a senha salva.
API password (Baltic): sua senha do serviço web da DPD Baltic. Não é necessária para a DPD Eslováquia. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor somente se quiser alterá-la.
Pickup points: o botão Refresh pickup points limpa o cache e carrega agora os pontos de retirada da DPD: Lituânia, Letônia e Estônia para a API Baltic, e uma busca de teste em Bratislava para a DPD Eslováquia. Ele mostra a quantidade de pontos de retirada ou o erro de cada país. Salve as configurações antes.
Preços
Os valores de frete são fixos por país, na moeda padrão da sua loja, sem impostos. Os preços da DPD não são solicitados à API.
Country prices: uma linha por país: CC:valor, por exemplo EE:3.50. Aceita-se vírgula decimal. Padrão: SK:3.50, LT:4.00, LV:4.00, EE:4.00.
Fallback cost: o valor para os países que não estão em Country prices. Padrão: 5.00. Deixe vazio para oferecer a transportadora somente nos países listados.
Calculation type: Per order cobra o valor uma única vez. Per item (price x quantity) multiplica o valor pela quantidade de itens no carrinho.
Free shipping from: o frete é grátis quando o subtotal do pedido (após descontos, antes dos impostos) atinge este valor. Deixe vazio para desativar.
Disponibilidade
A transportadora também fica oculta quando a DPD não retorna pontos de retirada para o endereço do cliente ou quando a API da DPD não pode ser acessada, porque um pedido não pode ser entregue sem ponto de retirada.
Min weight (kg): o peso mínimo do carrinho. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja. Vazio ou 0 significa sem limite.
Max weight (kg): carrinhos mais pesados não veem a transportadora. Padrão: 31.5. 0 significa sem limite. Confira os limites de peso de pacotes dos pontos de retirada e armários da DPD no seu país. Um Min weight (kg) maior que o Max weight (kg) é recusado, e nada é salvo.
Minimum subtotal: mostra a transportadora somente quando o subtotal do pedido (após descontos, antes dos impostos) é de pelo menos este valor. Deixe vazio para mostrá-la sempre.
Ignore shipping zones: quando ativada, a transportadora fica vinculada a todas as zonas e é oferecida para os países abaixo. Uma zona criada depois é vinculada imediatamente. Quando desativada, a transportadora é oferecida somente nas suas zonas em Shipping > Carriers. Ao desativar, a transportadora volta às zonas que tinha antes.
Countries: os países de destino para esse modo. Deixe vazio para todos os países. Usado somente com Ignore shipping zones.
Seletor de ponto de retirada
City order: mostra primeiro as principais cidades (Tallinn, Riga, Vilnius, Bratislava e outras). Ativado por padrão.
City list width: a largura CSS da lista de cidades, por exemplo 100% ou 300px. Padrão: 100%.
Pickup point list width: a largura CSS da lista de pontos de retirada, por exemplo 100% ou 400px. Padrão: 100%.
Avançado
Debug log: grava as requisições à API e as etapas da finalização de compra em logs/vfd_dpd_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros da API são sempre registrados, mesmo com esta opção desativada. As credenciais nunca são registradas.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativada, desinstalar o módulo apaga as suas configurações e a transportadora. O ponto de retirada salvo nos pedidos é sempre mantido.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o valor da DPD Pickup. Só produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica os países (com Ignore shipping zones), o peso do carrinho e o subtotal mínimo, obtém o valor do país (ou o custo alternativo) e aplica o frete grátis se o subtotal for suficiente. Em seguida, carrega os pontos de retirada da DPD para o endereço. Se a DPD não retornar nenhum, não puder ser acessada ou se as credenciais Baltic estiverem ausentes, a transportadora fica oculta. O valor é calculado na moeda padrão e depois exibido na moeda do carrinho do cliente.
A lista de pontos de retirada fica em cache por 24 horas, e uma lista vazia por 1 hora. Uma requisição com falha fica registrada por 5 minutos, para que uma queda da DPD nunca deixe a finalização de compra mais lenta. O tempo limite da API é de 15 segundos.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
O módulo não consulta preços na DPD, não cria envios DPD, não imprime etiquetas, não cria manifestos, não solicita coletas de courier, não rastreia encomendas e não exibe mapa. Somente o serviço web da DPD Baltic e a busca de parcelshops da DPD Eslováquia são suportados.
Pontos de retirada
Quando o cliente seleciona a DPD Pickup, aparecem uma lista de cidades e uma lista de pontos de retirada abaixo da transportadora. A cidade do endereço do cliente já vem selecionada. A escolha é salva no carrinho assim que o cliente a faz. Com a DPD Eslováquia, o cliente vê Enter your city and postcode to see the DPD pickup points nearby. até o endereço estar completo, e depois os pontos próximos. Se a DPD não tiver pontos para o endereço, o cliente vê No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.
Um ponto de retirada é obrigatório. Sem ele, o cliente não consegue prosseguir e vê Please select a DPD pickup point. O servidor confere se o ponto pertence à lista da DPD para o endereço do cliente. Uma escolha forjada ou desatualizada é recusada com The selected DPD pickup point is not available for this address. Please choose another one.
O ponto escolhido é salvo no pedido. Ele aparece na página de confirmação do pedido e nos detalhes do pedido do cliente como DPD pickup point:. No e-mail de confirmação do pedido, ele é incluído depois do nome da transportadora. O novo e-mail de pedido para a loja (ps_emailalerts) também mostra o ID do ponto. O nome salvo no pedido vem da DPD, não do navegador.
Na página do pedido no back office, o bloco DPD pickup point mostra o nome do ponto, o seu ID e o país. Clique em Edit, escolha uma cidade e outro ponto e clique em Save. O ponto é conferido com a lista da DPD para o endereço do pedido, e a página mostra Pickup point updated. ou Pickup point not found for the order address. Alterar o ponto exige permissão para editar pedidos, não acesso às páginas de Modules. Cada alteração é registrada em Advanced Parameters > Logs do pedido, com o ponto anterior, o novo ponto e o funcionário. Para alterar o ponto com a DPD Eslováquia, o pedido precisa ter cidade e CEP de entrega.
Se um carrinho for dividido em vários pedidos, o ponto de retirada fica com o primeiro pedido. Os demais pedidos mostram No pickup point was selected for this order., o log de depuração tem um erro para cada um deles, e o Edit ali mostra The pickup point of this cart belongs to another order of the same cart. Nothing was changed. O ponto de um pedido desse tipo deve ser informado à DPD manualmente.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox DPD Pickup é o primeiro bloco de Modules > Module Manager > VibeFox DPD Pickup > Configure, acima das configurações. Insira a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-shipping-dpd-pickup e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a transportadora DPD Pickup não é exibida aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A DPD Pickup não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo de clientes (ou se Ignore shipping zones está ligado e o país é permitido). Veja os avisos no topo da página do módulo e clique em Refresh pickup points. Confira os limites de peso e de subtotal e se o país tem um valor (ou um custo alternativo). Os produtos também podem estar limitados a certas transportadoras na página do produto.
Um erro depois de Refresh pickup points: o resultado mostra o erro da DPD para cada país. Por exemplo, "Login failed" significa que a DPD recusou as credenciais Baltic, então nenhum ponto de retirada pode ser carregado. Confira o nome de usuário e a senha da API com a DPD.
A DPD Eslováquia não mostra pontos: os pontos aparecem quando o cliente informa a cidade e o CEP. A DPD lista somente os pontos a até 50 km desse endereço. Os desenvolvedores podem alterar o raio com o hook do módulo actionVfdDpdSkSearchRadius.
Para descobrir o motivo: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Cada decisão é gravada ali. Os erros da API são sempre registrados. Nomes de usuário e senhas da API nunca são gravados no log.
Os pontos de retirada parecem desatualizados depois de uma alteração: clique em Save ou em Refresh pickup points na página do módulo. Ambos limpam as listas em cache.
A página informa que a transportadora DPD Pickup não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox DPD Pickup e escolha Uninstall. A chave de licença, o status da licença e o cache dos pontos de retirada são sempre removidos. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e as escolhas de carrinhos não finalizados são removidos. Se estiver desligado, a transportadora é apenas desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, ou em um Reset, a transportadora salva recupera o status que tinha antes: uma transportadora que você havia desativado continua desativada. O ponto de retirada salvo nos pedidos nunca é excluído.
DPD é uma marca de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela DPD.