VibeFox The Courier Guy 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.
Chave de API da ShipLogic (para tarifas em tempo real e lockers): a The Courier Guy opera na plataforma ShipLogic. Crie uma chave de API no portal de couriers da The Courier Guy, em Settings > API Keys (conta empresarial). Sem a chave, apenas a tabela de preços é usada e a transportadora locker não é oferecida.
Envio para a África do Sul: tarifas em tempo real e lockers são apenas para endereços sul-africanos. A África do Sul precisa ser um país ativo da loja (International > Locations > Countries).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 envio terminar, clique em Configure ou encontre VibeFox The Courier Guy depois na lista de módulos e clique em Configure.
3. Cole 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. Informe a API key da ShipLogic. Para tarifas em tempo real, preencha o endereço do remetente (rua, cidade, província, CEP) e, se a moeda da sua loja não for ZAR, a ZAR conversion rate.
5. Preencha a tabela de preços e/ou um custo alternativo e clique em Save.
6. Para tarifas de courier em tempo real, clique em Add South African provinces na seção Advanced se a página indicar que os endereços sul-africanos não têm província.
Na instalação, o módulo cria duas transportadoras: The Courier Guy (texto do prazo de entrega The Courier Guy courier delivery to your door) e The Courier Guy locker (Delivery to a TCG locker of your choice). Ambas estão ativas, vinculadas à zona da África do Sul e a todos os grupos de clientes. 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 estão na página do módulo: Modules > Module Manager > VibeFox The Courier Guy > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento limpa as tarifas e os lockers em cache e o último erro da ShipLogic. Os avisos no topo da página informam quando a África do Sul não é um país ativo, quando a chave de API, a taxa de conversão ZAR ou o endereço do remetente estão faltando, quando não há tabela de preços nem custo alternativo, quando os endereços sul-africanos não têm província, quando a unidade de peso ou de dimensão da loja não é reconhecida pelo módulo, ou quando a última requisição à ShipLogic falhou (com a data e o erro). Um número inválido (por exemplo, negativo) não é salvo: a página indica o campo e mantém o valor anterior.
Geral
Courier to the door: liga ou desliga a transportadora de courier. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Courier carrier name: o nome da transportadora de courier no checkout. Padrão: The Courier Guy. Obrigatório.
TCG locker: liga ou desliga a transportadora locker. O cliente escolhe um locker na finalização de compra. É oferecida apenas para endereços sul-africanos e somente com a chave de API da ShipLogic.
Locker carrier name: o nome da transportadora locker na finalização de compra. Padrão: The Courier Guy locker. Obrigatório.
Tax status: a regra de imposto das duas transportadoras. Taxable: <tax rule>: as tarifas em tempo real são obtidas sem IVA e o PrestaShop adiciona o imposto de frete da regra selecionada. None: as tarifas em tempo real são obtidas com IVA incluso.
API da ShipLogic (tarifas em tempo real e lockers)
API key: a sua chave de API da ShipLogic obtida no portal da The Courier Guy. Ela nunca é mostrada aos clientes nem gravada no log. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Digite um novo valor apenas para alterá-la. Marque Remove the saved API key e salve para removê-la.
Account ID: opcional. O ID numérico da conta da ShipLogic, somente se a sua chave tiver acesso a várias contas. Um valor que não seja numérico não é salvo.
Tarifas em tempo real (para endereços sul-africanos; se nenhuma tarifa em tempo real estiver disponível, a tabela de preços é usada)
Price source: de onde vem o preço.
ZAR conversion rate: a ShipLogic cota em rands sul-africanos (ZAR). Se a moeda padrão da sua loja não for ZAR, informe quanto vale 1 ZAR na sua moeda, por exemplo 0.05. Sem isso, as tarifas em tempo real não são usadas e vale a tabela de preços. Se a moeda da sua loja for ZAR, deixe o campo vazio. A taxa não é atualizada automaticamente.
Endereço do remetente (para tarifas em tempo real) (onde a The Courier Guy coleta as encomendas, na África do Sul; rua, cidade, província e CEP são necessários para tarifas em tempo real)
Sender company: o nome da sua empresa.
Sender street address: por exemplo, 12 My Road.
Sender suburb: o bairro do endereço do remetente.
Sender city: a cidade do endereço do remetente.
Sender province: escolha a província sul-africana na lista.
Sender postal code: o CEP do endereço do remetente.
Tabela de preços (seus próprios preços na moeda padrão da loja, sem impostos: usada com Price table only, fora da África do Sul e sempre que não houver tarifa em tempo real; aceita-se vírgula ou ponto decimal)
Calculation type: aplica-se apenas à tabela de preços. Uma tarifa em tempo real é sempre para o pedido inteiro.
Prices by weight: uma tabela de países com uma coluna Price e as faixas de peso XS (até 1 kg), S (até 2 kg), M (até 3 kg), L (até 5 kg) e XL (acima de 5 kg). Clique em Add row para adicionar uma linha (uma nova linha começa com a África do Sul) e no ícone de lixeira para remover uma. Uma faixa vazia ou igual a 0 usa a coluna Price. Um preço de 0 significa frete grátis. A linha * Any country se aplica a países sem linha própria e a uma linha de país sem nenhum preço. Um preço que não seja um número é apagado, e a página o lista.
Fallback cost: usado quando não há nem tarifa em tempo real nem preço na tabela. Deixe vazio para ocultar as transportadoras nesse caso.
Condições (ambas as transportadoras)
Min weight (kg): oculta as transportadoras abaixo deste peso do carrinho. 0 significa sem limite.
Max weight (kg): oculta as transportadoras acima deste peso do carrinho. Padrão: 30. 0 significa sem limite, vazio significa 30 kg. Se Min weight (kg) for maior que Max weight (kg), a página mostra um aviso e ambos os limites mantêm os valores anteriores.
Minimum order amount: mostra as transportadoras apenas a partir deste subtotal do carrinho (produtos que precisam de envio, sem impostos, após descontos). Deixe vazio para mostrá-las sempre.
Free shipping from: o subtotal do carrinho a partir do qual a entrega é grátis. Deixe vazio para nunca oferecer frete grátis. Quando o subtotal atinge esse valor, as transportadoras são mostradas com preço 0 e nenhuma requisição é enviada à ShipLogic para a tarifa.
Disponibilidade sem zonas de entrega
Normalmente, as transportadoras são oferecidas nas zonas de entrega às quais estão vinculadas em Shipping > Carriers.
Ignore shipping zones: oferece a transportadora do tipo de entrega abaixo para os países abaixo, mesmo onde as suas zonas não os incluem. A transportadora fica vinculada a todas as zonas ativas, inclusive às criadas depois. Ao desligar a opção novamente, ela recupera as zonas que tinha antes.
Delivery type without zones: Courier to the door ou TCG locker (customer chooses a locker). Usado apenas com Ignore shipping zones.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Os lockers são oferecidos apenas na África do Sul.
Avançado
South African provinces: o PrestaShop não tem províncias sul-africanas, mas a tarifa de courier em tempo real precisa da província do endereço. Add South African provinces adiciona as 9 províncias (EC, FS, GP, KZN, LP, MP, NC, NW, WC) como estados da África do Sul e mostra o campo de estado nos endereços sul-africanos. As províncias que já existem não são adicionadas de novo. Até lá, o courier recebe o preço da tabela.
Debug log: grava mensagens de depuração em logs/vfd_tcgr_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros de API são sempre registrados, mesmo com esta opção desligada. A chave de API e os dados dos clientes nunca são registrados.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ligada, ao desinstalar o módulo, suas configurações e transportadoras são excluídas. Quando desligada, desinstalar apenas desliga as transportadoras. Os lockers salvos em pedidos são sempre mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço de cada transportadora. Só contam os produtos físicos: produtos virtuais não somam peso nem entram no valor do pedido. O módulo verifica primeiro as condições: peso do carrinho e valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0.
Courier to the door: o módulo pede à ShipLogic o serviço mais barato do endereço do remetente até o endereço do cliente. O endereço precisa ter rua, cidade, província e CEP. Até lá, usa-se a tabela de preços.
TCG locker: a tarifa em tempo real é o serviço mais barato de porta até o locker mais próximo da cidade do cliente. Ela não é recalculada para o locker que o cliente escolher. A transportadora locker aparece apenas para endereços sul-africanos e somente com a chave de API.
O pedido inteiro é cotado como uma única encomenda: o peso total, o maior comprimento e a maior largura, e as alturas empilhadas. Produtos sem dimensões contam como cubos de 10 cm. Pesos e dimensões são convertidos das unidades da sua loja. O valor em rands é convertido para a moeda padrão e depois exibido na moeda do carrinho do cliente.
As requisições à ShipLogic expiram em 12 segundos. As tarifas ficam em cache por 1 hora, os lockers por 6 horas e as falhas por 10 minutos, para que uma API lenta não atrase cada atualização da finalização de compra. Se não houver tarifa em tempo real, o preço vem da tabela e, depois, do Fallback cost. Se nenhum se aplicar, a transportadora fica oculta. Erros da API nunca são mostrados ao cliente.
As transportadoras funcionam nos temas Classic e Hummingbird. Se você editar uma transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo segue a nova versão automaticamente.
O módulo não agenda envios, não cria conhecimentos de transporte nem etiquetas e não atualiza o rastreamento automaticamente. Não há mapa de lockers: os lockers são escolhidos em uma lista. Tarifas em tempo real e lockers são apenas para a África do Sul. Os demais países recebem a tabela de preços. Apenas uma tarifa por transportadora (o nível de serviço mais barato) é exibida, sem escolha de níveis de serviço, seguro ou extras na finalização de compra.
Pontos de retirada
Quando o cliente escolhe a transportadora locker, aparece um seletor de lockers abaixo dela. Ele lista os lockers que a ShipLogic retorna para a cidade do endereço de entrega, do mais próximo para o mais distante. O cliente pode digitar outra cidade, bairro ou CEP e clicar em Search. Um locker precisa ser escolhido antes que o cliente possa continuar: caso contrário, a etapa de envio mostra Please choose a The Courier Guy locker.
O locker é verificado novamente no servidor contra a lista da ShipLogic, também ao concluir o pedido. Nome e fornecedor vêm da ShipLogic, nunca do navegador. A escolha fica salva no carrinho e é redefinida quando o endereço de entrega muda.
Se a ShipLogic não puder ser acessada, o seletor informa que os lockers não puderam ser carregados e que a loja entrará em contato com o cliente sobre o locker. O pedido pode então ser feito sem locker. Ele é sinalizado na página de pedido do back office: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.
Pedidos
O locker escolhido (nome, ID e fornecedor) é salvo com o pedido. Ele aparece no bloco The Courier Guy da página de pedido do back office, na página de confirmação do pedido, nos detalhes do pedido do cliente e no e-mail de confirmação do pedido. O e-mail de "novo pedido" da loja (módulo Mail alerts) também mostra o ID do locker, ou que nenhum locker foi escolhido porque a ShipLogic estava indisponível.
Código de rastreamento da The Courier Guy: agende a encomenda no seu portal da The Courier Guy e informe a referência como código de rastreamento do envio no bloco Shipping do pedido (Edit). O bloco The Courier Guy o mostra. O cliente o vê nos detalhes do pedido e recebe o e-mail "em trânsito" do PrestaShop.
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 The Courier Guy é o primeiro bloco da página Modules > Module Manager > VibeFox The Courier Guy > Configure, 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 estão a linha Product: presta-shipping-the-courier-guy e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Apenas 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 único 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 vibefox.net.
Sem uma chave ativa, nenhuma das transportadoras The Courier Guy (courier to the door ou TCG locker) é 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 as transportadoras também ficam ocultas 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. 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 inserção da chave e depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar o módulo sempre remove a chave de licença e o status da licença. O Reset deste módulo não apaga dados, então a chave e o status são mantidos.
Solução de problemas
A The Courier Guy não aparece na finalização de compra: verifique se a licença está ativa e se a transportadora está ligada (Courier to the door ou TCG locker). Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente (ou se Ignore shipping zones está ligado e o país é permitido). Confira os limites de peso e o Minimum order amount. Confirme que a tabela ou o Fallback cost tem um preço. A transportadora locker aparece apenas para endereços sul-africanos e com a chave de API. Além disso, os produtos podem ser limitados a certas transportadoras na página do produto.
Os clientes não veem a lista de lockers: os lockers exigem a chave de API, a transportadora TCG locker ligada e um endereço de entrega na África do Sul. A página de configurações mostra o último erro da ShipLogic, se houver, por exemplo uma chave recusada.
O preço é sempre o da tabela: verifique os avisos na página de configurações. Uma tarifa em tempo real exige a chave de API, o endereço completo do remetente e, para lojas que não usam rands, a taxa de conversão ZAR. Para entrega em domicílio, o endereço do cliente precisa de rua, cidade, província e CEP: adicione as províncias sul-africanas na seção Advanced. Para lockers, a ShipLogic precisa encontrar um locker perto da cidade do cliente. Ative o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo.
A ShipLogic está fora do ar: é mostrado o preço da tabela ou o custo alternativo. Pedidos com locker podem ser feitos sem locker e são sinalizados no pedido.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as tarifas e os lockers em cache.
A página informa que uma transportadora The Courier Guy não foi encontrada: 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 suas configurações e o status ligado/desligado das transportadoras existentes.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox The Courier Guy e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As tarifas e os lockers em cache e o último erro da ShipLogic são sempre removidos. Se Remove data on uninstall estiver ligado, as transportadoras são excluídas (os pedidos mantêm o histórico), e as configurações, o log e os lockers de carrinhos sem pedido são removidos. Se estiver desligado, as transportadoras apenas são desligadas e todas as configurações são mantidas. Instalar o módulo novamente devolve às transportadoras o status que tinham. Lockers salvos em pedidos nunca são removidos.
The Courier Guy e a ShipLogic são marcas registradas de seus respectivos proprietários. Este módulo não é afiliado nem endossado pela The Courier Guy ou pela ShipLogic.