VibeFox DPD Pickup for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Credenciais DPD Baltic (Lituânia, Letônia, Estônia): a lista de pontos de retirada vem do serviço web DPD Baltic. Você precisa do nome de usuário e da senha da API que a DPD fornece aos seus clientes empresariais. Peça ao seu gerente de conta DPD ou ao atendimento ao cliente DPD do seu país. Uma conta DPD Baltic 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.

Classe de peso: os pesos dos produtos são convertidos para kg. A sua loja precisa de uma classe de peso com a unidade kg em System > Localisation > Weight Classes (o OpenCart tem uma por padrão).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_dpd_pickup-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_dpd_pickup.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. Na administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_dpd_pickup-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do Installer, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox DPD Pickup e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Insira a sua chave de licença VibeFox em License key no bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).

5. Escolha a sua API DPD. Para DPD Lituânia, Letônia ou Estônia, informe o nome de usuário e a senha da API. Confira os preços por país, ative Enable/Disable e clique em Save. Depois clique em Refresh pickup points para verificar a conexão (veja Configuração).

OpenCart 4

1. Na administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_dpd_pickup.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox DPD Pickup, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Insira a chave de licença e as configurações como nos passos 4 e 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Depois da instalação, o método fica desativado até você ativar Enable/Disable e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações mantidas serão usadas de novo.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as listas de pontos de retirada em cache. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações, atualizar os pontos de retirada ou limpar o log.

Os avisos no topo da página informam quando o nome de usuário ou a senha da DPD Baltic estão vazios, ou quando nenhum preço está definido (nos dois casos o método não aparece na finalização de compra), e quando a loja não tem uma classe de peso com a unidade kg (os pesos dos produtos são então lidos pelo nome da unidade, e unidades desconhecidas são tratadas como kg). Alguns valores impedem o salvamento, e nesse caso nada é salvo: um Name vazio ou com mais de 64 caracteres, um Sort order que não é um número inteiro e um Min weight (kg) maior que o Max weight (kg). Um valor que não é número, ou um número negativo, em um campo de valor ou de peso não é salvo: o campo fica vazio e um aviso o indica, enquanto as demais configurações são salvas. As linhas de Country prices que não estão no formato CC:PRICE são listadas em um aviso e ignoradas.

Geral

O método é oferecido na zona geográfica definida em Availability (todas as zonas, se nenhuma for escolhida), ou com Ignore shipping zones nos países escolhidos ali.

Enable/Disable: mostra ou oculta o DPD Pickup na finalização de compra. Padrão: desativado.

Name: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: DPD Pickup Point. Obrigatório, no máximo 64 caracteres.

Tax class: a classe de imposto aplicada ao valor do envio, ou None (padrão) para nenhum imposto.

Sort order: a posição do método na lista de métodos de envio. Um número inteiro.

Lista de pontos de retirada DPD

Os pontos de retirada são carregados da DPD e ficam em cache (veja Como funciona na finalização de compra).

DPD API: a empresa DPD com a qual você tem conta. Contas Baltic usam o serviço web do próprio país.

API username (Baltic): o seu nome de usuário do serviço web DPD Baltic. Não é necessário para a DPD Eslováquia. Apagá-lo também apaga a senha salva.

API password (Baltic): a sua senha do serviço web 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 para alterá-lo.

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 por país. Salve as configurações antes.

Preços

Os valores de envio são fixos por país, na moeda padrão da sua loja, sem impostos. Os preços da DPD não são consultados na API.

Country prices: uma linha por país: CC:preço, por exemplo EE:3.50. A vírgula decimal é aceita. Padrão: SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost: o preço para países que não estão em Country prices. Padrão: 5.00. Deixe vazio para oferecer o método somente nos países listados.

Calculation type: Per order (padrão) cobra o preço uma vez. Per item (price x quantity) multiplica pelo número de itens no carrinho.

Free shipping from: o envio é grátis quando o subtotal do pedido (após descontos, antes dos impostos) atinge este valor. Deixe vazio para desativar.

Disponibilidade

O método também fica oculto 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 classe de peso. Vazio ou 0 significa sem limite.

Max weight (kg): carrinhos mais pesados não veem o método. Padrão: 31.5. Vazio ou 0 significa sem limite. Confira os limites de peso de encomendas dos pontos e armários DPD Pickup do seu país.

Minimum subtotal: mostra o método somente quando o subtotal do pedido (após descontos, antes dos impostos) é pelo menos este valor. Deixe vazio para mostrá-lo sempre.

Geo zone: oferece o método somente para endereços dentro desta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usado com Ignore shipping zones.

Ignore shipping zones: quando ativado, a zona geográfica não é verificada e o método é oferecido nos países indicados abaixo. Quando desativado (padrão), somente a zona geográfica acima é usada.

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 storage/logs/vfd_dpd_debug.log.php (no OpenCart 4, system/storage/logs/vfd_dpd_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. As credenciais nunca são registradas. Quando o arquivo atinge 5 MB, ele é movido para vfd_dpd_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão apaga as suas configurações, o log e as escolhas de finalizações de compra não concluídas. O ponto de retirada salvo nos pedidos é sempre mantido.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A senha da API não é exportada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. A senha da API salva é mantida.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do DPD Pickup. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Só contam os produtos com Requires Shipping definido como Yes: os outros produtos não somam peso e não entram no subtotal. A extensão verifica os países (com Ignore shipping zones), o peso do carrinho e o subtotal mínimo, pega o preço do país (ou o custo alternativo) e aplica o frete grátis se o subtotal for alto o suficiente. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos.

Em seguida, ela 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 faltarem as credenciais Baltic, o método fica oculto. Com a DPD Eslováquia, o método é mostrado enquanto a cidade ou o CEP ainda estiverem faltando, e os pontos aparecem quando o endereço estiver completo. O preço é calculado na moeda padrão e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

Uma lista de pontos de retirada fica em cache por até 24 horas, uma lista vazia por até 1 hora, mas nunca por mais tempo que a duração do cache do OpenCart (1 hora por padrão). Uma requisição com falha é lembrada 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.

A extensão não consulta preços da DPD, não cria envios DPD, não imprime etiquetas, não gera manifestos, não agenda coletas de courier, não rastreia encomendas e não mostra mapa. Somente o serviço web DPD Baltic e a busca de parcelshops da DPD Eslováquia são suportados.

Pontos de retirada

Quando o cliente seleciona o DPD Pickup, aparecem uma lista de cidades e uma lista de pontos de retirada abaixo do método. A cidade do endereço do cliente já vem selecionada. A escolha é salva 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 ficar 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 continuar e vê Please select a DPD pickup point. Quando o cliente clica em Continue, o servidor verifica se o ponto pertence à lista da DPD para o endereço do cliente. Uma escolha falsificada ou desatualizada é recusada com The selected DPD pickup point is not available for this address. Please choose another one. Se a lista da DPD não puder ser carregada naquele momento, o ponto que o cliente já havia escolhido é aceito, e o pedido mostra o ID dele em vez do nome.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe o DPD Pickup na janela Shipping method options. A lista de cidades e a lista de pontos de retirada aparecem nessa janela, abaixo do método, e funcionam como descrito acima. O botão Continue da janela não avança sem um ponto de retirada, com as mesmas mensagens.

O ponto escolhido é adicionado ao método de envio do pedido, por exemplo DPD Pickup Point: name, street, postcode city com o título padrão, ou My title - DPD pickup point: name, street, postcode city com o seu próprio título (no máximo 128 caracteres). Assim ele aparece no pedido na administração, no histórico de pedidos do cliente, nos e-mails do pedido e na fatura. O nome salvo no pedido vem da DPD, e não do navegador.

No OpenCart 4, o texto do método de envio pode ter até 255 caracteres. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza cada vez que o cliente confirma de novo, e o ponto de retirada do pedido é atualizado junto com ele.

Na página do pedido na administração (Sales > Orders), o painel DPD pickup point acima do histórico mostra o nome do ponto, o 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 o painel mostra Pickup point updated. ou Pickup point not found for the order address. O texto do método de envio do pedido é atualizado, e uma nota é adicionada ao histórico do pedido (não enviada ao cliente) com o ponto antigo, o novo ponto e o usuário administrador. Alterar o ponto exige a permissão de modificação de pedidos, e não o acesso às configurações da extensão. Com a DPD Eslováquia, o pedido precisa de cidade e CEP de entrega, senão o painel mostra Add the shipping city and postcode to change the pickup point. Um pedido feito sem ponto mostra No pickup point was selected for this order., e o log de depuração tem um erro para ele. O painel e o Edit também funcionam depois que a extensão é desativada.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox DPD Pickup é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit, acima das configurações. Cole 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 ficam a linha Product: opencart-shipping-dpd-pickup e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma da administração (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 de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, o método de envio DPD Pickup não é mostrado aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado à administração no mesmo navegador ainda vê o método na loja, marcado com (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login da administração, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard da administração. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard da administração ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

DPD Pickup não aparece na finalização de compra: confira se a licença está ativa e se Enable/Disable está ativado. Verifique Geo zone (ou Ignore shipping zones e Countries), os limites de peso e de subtotal e se o país tem um preço (ou um custo alternativo). Veja os avisos no topo da página da extensão e clique em Refresh pickup points. Confira se os produtos têm Requires Shipping definido como Yes.

Um erro depois de Refresh pickup points: o resultado mostra o erro da DPD por 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.

Para encontrar o motivo: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. 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 mudança: clique em Save ou em Refresh pickup points na página da extensão. Ambos limpam as listas em cache.

A página mostra "Warning: You do not have permission to modify VibeFox DPD Pickup!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_dpd_pickup (OpenCart 3) ou extension/vfd_dpd_pickup/shipping/vfd_dpd_pickup (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o raio de busca da DPD Eslováquia pode ser alterado por outra extensão com o evento do OpenCart vfd_dpd_pickup/sk_search_radius.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox DPD Pickup. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax class e Geo zone. A extensão sempre remove os seus eventos e as listas de pontos de retirada em cache. Se Remove data on uninstall estiver ativado, as demais configurações, o log de depuração e as escolhas de finalizações de compra não concluídas também são apagados. Se estiver desativado, as configurações são mantidas e usadas novamente quando você instalar a extensão de novo. O ponto de retirada salvo nos pedidos nunca é apagado, e os pedidos existentes mantêm o seu método de envio e o seu custo.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox DPD Pickup na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

DPD é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela DPD.