VibeFox Correos CityPaq for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Entrega na Espanha: os armários CityPaq existem apenas na Espanha, por isso a transportadora só é oferecida para endereços de entrega na Espanha.
Credenciais da API da Correos (somente para a lista ao vivo de armários): a lista de armários CityPaq da Correos lê os armários ativos da API "terminals" da Correos. No portal de desenvolvedores da Correos, abra a API "terminals" e use Request access para a sua aplicação. A Correos aprova as solicitações dos seus clientes empresariais e envia um client ID e um client secret. Eles também aparecem em My applications no portal. Se os clientes digitarem o armário por conta própria ou escolherem na sua lista, você não precisa de credenciais da API.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o upload terminar, clique em Configure, ou encontre VibeFox Correos CityPaq na lista de módulos depois e clique em Configure.
3. Informe a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Preencha a tabela de preços, escolha como o cliente seleciona o armário (veja Configuração) e clique em Save.
Na instalação, o módulo cria a transportadora Correos CityPaq com o texto do prazo de entrega Delivery to a Correos CityPaq parcel locker. A transportadora é associada a todos os grupos de clientes e à zona Espanha. Você pode alterar zonas, grupos de clientes, 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 ficam na página do módulo: Modules > Module Manager > VibeFox Correos CityPaq > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Preços e valores aceitam vírgula ou ponto decimal.
Os avisos acima das configurações informam quando a transportadora não foi encontrada, quando a tabela de preços não tem linha para a Espanha nem linha padrão, quando a seleção de armário escolhida não pode funcionar (nenhum armário na sua lista, sem credenciais da API), qual foi o último erro da API da Correos, e quando a unidade de peso da sua loja não é conhecida pelo módulo (os pesos dos produtos são então lidos como kg; defina kg, g, lb ou oz em International > Localization). Se o nome estiver vazio, for inválido ou tiver mais de 64 caracteres, se um peso ou valor não for um número válido igual ou maior que 0, ou se Min weight (kg) for maior que Max weight (kg), a página mostra um erro e nada é salvo. Preços inválidos na tabela de preços e linhas inválidas ou duplicadas em My lockers são informados como avisos, e o restante é salvo.
Geral
Os armários CityPaq existem apenas na Espanha, por isso a transportadora nunca é oferecida para outros países.
Enable/Disable: liga ou desliga o envio Correos CityPaq. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome do método de envio exibido ao cliente na finalização de compra. Também é o nome da transportadora. Padrão: Correos CityPaq. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora. O PrestaShop adiciona este imposto sobre os preços da tabela. No tax significa que os preços são finais.
Preços (o título da seção mostra a moeda padrão da sua loja)
A Correos não publica uma API de tarifas para o CityPaq, por isso o preço vem desta tabela. Informe os preços do seu contrato com a Correos na moeda padrão da loja, sem impostos.
Price table: uma linha para Spain (ES) e/ou uma linha padrão * Default. Cada linha tem um Price base e preços opcionais para os tamanhos de pacote XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Um preço de tamanho igual a 0 ou vazio usa o preço base. Clique em + Add row para adicionar uma linha e no ícone de lixeira para remover uma. Sem uma linha correspondente, a transportadora fica oculta. Se um país aparecer duas vezes, só a primeira linha é usada.
Calculation type: como o tamanho do pacote é determinado.
Os pesos dos produtos são convertidos para kg a partir da unidade de peso da sua loja (por exemplo, kg, g, lb ou oz).
Condições
Min weight (kg): oculta a transportadora quando o carrinho é mais leve. 0 significa sem limite.
Max weight (kg): oculta a transportadora quando o carrinho é mais pesado. Padrão: 30, porque o CityPaq aceita pacotes de até 30 kg. 0 significa sem limite.
Minimum order amount: mostra a transportadora apenas quando o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) atinge este valor. Deixe vazio para mostrar sempre.
Frete grátis
Free shipping: ativa a entrega CityPaq gratuita a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual esta transportadora custa 0. Usado apenas quando Free shipping está ativado.
Seleção de armário CityPaq
A seção tem um link para o localizador oficial de armários CityPaq da Correos.
Locker selection: como o cliente escolhe o armário antes de fazer o pedido. Padrão: o cliente digita o armário.
Se você escolher a lista da Correos sem credenciais da API, ou a sua própria lista enquanto My lockers estiver vazio, os clientes são solicitados a informar o armário.
My lockers: usado quando Locker selection está configurado para a sua lista. Um armário por linha: CODE | Name | Address | Postal code | City. O código e o nome são obrigatórios. Se um código estiver listado duas vezes, somente a primeira linha é usada.
Lista Correos CityPaq (API) (usada somente com a lista Correos CityPaq)
A seção tem um link para a página da API "terminals" no portal de desenvolvedores da Correos. Somente a lista de armários é lida. Os preços sempre vêm da tabela de preços.
API client ID: o client_id da sua aplicação no portal de desenvolvedores da Correos.
API client secret: o client_secret da sua aplicação no portal de desenvolvedores da Correos.
Depois de salvar, os dois campos ficam vazios e mostram Saved - leave empty to keep it. Digite um novo valor somente para alterá-lo. Marque Remove the saved client ID and client secret e clique em Save para excluí-los. Quando nada está salvo, a seção mostra No credentials saved. Ao alterar as credenciais ou a seleção de armário, as listas de armários em cache são apagadas.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o CityPaq para todos os endereços espanhóis, mesmo que a zona do endereço não esteja vinculada à transportadora. Quando ativado, a transportadora é vinculada a todas as zonas ativas, inclusive às criadas depois. Quando você desativar novamente, a transportadora volta a ter as zonas que tinha antes. Desativado (recomendado) significa que são usadas as zonas definidas em Shipping > Carriers.
Avançado
Debug log: grava linhas de depuração em logs/vfd_cpq_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros da API da Correos são sempre gravados, mesmo quando esta opção está desativada. Credenciais e dados pessoais nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo exclui as configurações, a transportadora, as listas em cache e os logs. Os armários salvos nos pedidos são mantidos. Quando desativado, tudo é mantido para uma reinstalação.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço do CityPaq. Somente produtos físicos contam: produtos virtuais não adicionam peso e não entram no valor do pedido. O módulo verifica se o endereço de entrega está na Espanha, o peso do carrinho e o valor mínimo do pedido, encontra a linha de preço da Espanha (ou a linha *) e o tamanho do pacote, e devolve o preço. Se o frete grátis se aplicar, o preço é 0. O preço é calculado na moeda padrão da sua loja e depois exibido na moeda do carrinho do cliente. O imposto é adicionado pela regra de imposto da transportadora.
Quando o cliente seleciona o CityPaq, a caixa CityPaq locker aparece abaixo da transportadora. A escolha é salva no carrinho assim que o cliente a faz. Um armário não aceitável é recusado com uma mensagem, e a escolha anterior permanece. Com a lista da Correos, um código de armário só é aceito se a Correos o tiver oferecido para o código postal pesquisado, e o nome e o endereço são obtidos da Correos. Um cliente pode pesquisar até 30 códigos postais diferentes por carrinho. Depois disso, ele vê Muitas pesquisas. Informe o armário CityPaq que você encontrou no mapa da Correos.
O botão Continue da etapa de envio não avança sem um armário válido. Isso também é verificado no servidor. O cliente vê, por exemplo, Escolha o armário CityPaq onde você quer retirar a sua encomenda. Quando o pedido é feito, o armário do carrinho é salvo no pedido.
A lista da Correos só é solicitada quando o cliente seleciona o CityPaq, e não para cada visitante da etapa de envio. Uma lista fica em cache por 12 horas por código postal. Uma solicitação que falhou fica em cache por 10 minutos, para que a finalização de compra não espere pela Correos a cada atualização. O tempo limite da API é de 12 segundos. O cliente nunca vê o erro técnico, apenas uma mensagem curta e o campo manual. A caixa do armário funciona com os temas Classic e Hummingbird.
O módulo não obtém tarifas em tempo real da Correos, não exibe um mapa, não pré-registra envios, não imprime etiquetas, não solicita coletas e não rastreia pacotes. Crie o envio na sua conta da Correos usando o armário salvo no pedido.
Pontos de retirada
O armário escolhido é salvo no pedido. O cliente o vê como CityPaq locker: na página de confirmação do pedido e na página de detalhes do pedido na conta dele. No e-mail de confirmação do pedido e no e-mail de novo pedido do módulo Mail alerts, o armário é acrescentado à linha da transportadora, por exemplo Correos CityPaq - CityPaq locker: ....
Na página do pedido na administração, o bloco CityPaq locker mostra o armário e o seu Locker code: quando ele foi escolhido em uma lista. Para alterá-lo, use o campo Change CityPaq locker e clique em Save: com a sua lista, escolha outro armário na lista suspensa; com a lista da Correos, digite um código de armário (ele é consultado na Correos) ou um endereço; nos outros casos, digite um novo código ou endereço. Deixe o campo vazio para manter o armário atual. Cada alteração adiciona uma mensagem privada ao pedido: Armário CityPaq alterado para: .... Alterar o armário exige permissão para editar pedidos. Não é necessário acesso às páginas Modules.
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 Correos CityPaq é o primeiro bloco em Modules > Module Manager > VibeFox Correos CityPaq > Configure, acima das configurações. Informe 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-correos-citypaq 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 do 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 Correos CityPaq 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ê: é possível 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 exigem uma 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 informada e depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
O Correos CityPaq não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o endereço de entrega está na Espanha. Em Shipping > Carriers, verifique se a transportadora cobre a zona Espanha e o grupo do cliente (ou ative Ignore shipping zones). Verifique se a tabela de preços tem uma linha para a Espanha ou uma linha *, e se o carrinho está dentro dos limites de peso e de Minimum order amount. Além disso, os produtos podem estar limitados a determinadas transportadoras na página do produto.
Os clientes precisam digitar o armário mesmo com a lista da Correos selecionada: verifique se API client ID e API client secret estão salvos e leia o aviso acima das configurações. Ele mostra o último erro da API da Correos. HTTP 401/403 significa que a Correos recusou as credenciais: confira-as e verifique se a sua aplicação tem acesso à API "terminals". Após um erro, a próxima tentativa é feita 10 minutos depois.
Nenhum armário para um código postal: a Correos não encontrou armários ativos para esse código postal, a área dele ou a província. O cliente pode pesquisar outro código postal ou informar o armário encontrado no localizador CityPaq da Correos.
A lista suspensa de meus armários não aparece: My lockers está vazio ou suas linhas são inválidas. Cada linha precisa de pelo menos CODE | Name.
Onde os clientes encontram o código do armário: no localizador CityPaq da Correos, vinculado abaixo do campo do armário.
A página diz que a transportadora não foi encontrada, ou que não foi possível atualizá-la: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente. A redefinição mantém as configurações e o status da transportadora.
Notas para desenvolvedores: o armário de um carrinho e de um pedido é armazenado na tabela vfd_cpq_locker (com o prefixo do seu banco de dados). O módulo usa a API "terminals" de produção da Correos.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Correos CityPaq e escolha Uninstall. A chave de licença, o status da licença, as listas de armários da Correos em cache e o último erro da API são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os armários de carrinhos sem pedido são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Instalar o módulo novamente restaura o status anterior da transportadora. Os armários salvos nos pedidos nunca são excluídos.
Correos e CityPaq são marcas comerciais de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela Correos.