VibeFox The Courier Guy for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
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 seu 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 entrega em locker não pode ser oferecida.
Envio para a África do Sul: as tarifas em tempo real e os lockers são apenas para endereços sul-africanos. Sua loja precisa enviar para a África do Sul (WooCommerce > Settings > General > Shipping location(s)).
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_the_courier_guy para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox The Courier Guy, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira a API key da ShipLogic. Para as 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 o ZAR, a ZAR conversion rate.
6. Preencha a tabela de preços e/ou um custo alternativo.
7. Adicione VibeFox The Courier Guy a uma zona de entrega para a África do Sul em WooCommerce > Settings > Shipping > Shipping zones, escolha o Delivery type (courier ou TCG locker) e, se quiser, um título. Adicione-o uma segunda vez para o outro tipo de entrega.
Configuração
As configurações principais ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Elas valem para todas as zonas de entrega. Quando você adiciona o método a uma zona, a janela da zona tem dois campos:
Title (zone): o nome desta tarifa na finalização de compra, nesta zona. Deixe em branco para usar o Method name geral.
Delivery type (zone): Courier to the door (padrão) ou TCG locker (customer chooses a locker). Adicione o método duas vezes para oferecer os dois. Os lockers exigem a chave de API da ShipLogic e estão disponíveis apenas na África do Sul.
Sempre que você salva as configurações, as tarifas e os lockers em cache são apagados. Os avisos acima das configurações informam quando a loja não envia para a África do Sul, a chave de API está ausente, a taxa de conversão para ZAR ou o endereço do remetente está faltando, não há tabela de preços nem custo alternativo, ou a última requisição à ShipLogic falhou (com data e erro).
Geral
Enable/Disable: desativa o método em todos os lugares, inclusive nas zonas de entrega.
Method name: o nome exibido na finalização de compra. Para a entrega em locker, é acrescentado "locker", por exemplo "The Courier Guy locker". Uma zona pode substituí-lo pelo próprio título. Padrão: The Courier Guy.
Tax status: Taxable: as tarifas em tempo real são obtidas sem IVA e o WooCommerce adiciona o próprio imposto. None: as tarifas em tempo real são obtidas com IVA incluído.
API da ShipLogic (tarifas em tempo real e lockers)
API key: sua chave de API da ShipLogic obtida no portal da The Courier Guy.
Account ID: opcional. O ID numérico da conta ShipLogic, somente se sua chave tiver acesso a várias contas.
Tarifas em tempo real (para endereços sul-africanos; se não houver tarifa em tempo real, 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 da sua loja não for o ZAR, informe quanto vale 1 ZAR na moeda da loja, por exemplo 0.05. Sem esse valor, as tarifas em tempo real não são usadas e a tabela de preços é aplicada. Se a moeda da loja for o ZAR, deixe em branco. A taxa não é atualizada automaticamente.
Endereço do remetente (para tarifas em tempo real) (de onde a The Courier Guy retira as encomendas, na África do Sul; para as tarifas em tempo real, são necessários rua, cidade, província e CEP)
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 da loja: usados com Price table only, fora da África do Sul e sempre que não houver tarifa em tempo real; vírgula ou ponto decimal são aceitos)
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 X para removê-la. Uma faixa vazia ou 0 usa a coluna Price. Um preço de 0 significa frete grátis. A linha * Any country se aplica aos países sem linha própria e a uma linha de país sem nenhum preço.
Fallback cost: usado quando não há tarifa em tempo real nem preço na tabela. Deixe em branco para ocultar o método nesse caso.
Condições
Min weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite.
Max weight (kg): oculta o método acima deste peso do carrinho. Padrão: 30. 0 significa sem limite.
Minimum order amount: exibe o método somente a partir deste subtotal do carrinho. Deixe em branco para exibi-lo sempre.
Free shipping from: o subtotal do carrinho a partir do qual este método é gratuito. O frete grátis só é oferecido quando o método tem preço para o destino: uma tarifa em tempo real, um preço da tabela ou o Fallback cost. Se a tabela ou o Fallback cost tiverem preço, nenhuma requisição é enviada à ShipLogic para a tarifa. Deixe em branco para nunca oferecer frete grátis.
Excluded shipping classes: oculta o método se o carrinho contiver produtos destas classes de entrega do WooCommerce.
Disponibilidade sem zonas de entrega
Ignore shipping zones: oferece o método para os países abaixo, mesmo onde nenhuma zona o contenha.
Delivery type without zones: courier ou TCG locker para esse modo. Usado somente com Ignore shipping zones.
Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia. Os lockers são oferecidos somente na África do Sul.
Avançado
Debug log: grava mensagens de depuração em WooCommerce > Status > Logs, origem vfd-the-courier-guy. Erros da API são sempre registrados, mesmo com esta opção desativada. A chave de API e os dados dos clientes nunca são registrados.
Remove data on uninstall: se ativado, excluir o plugin remove as configurações e as tarifas por zona deste método. Desativar o plugin nunca apaga as configurações. Lockers e rastreamentos salvos nos pedidos são mantidos.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica primeiro as condições: peso do carrinho, valor mínimo do pedido e classes de entrega excluídas. Se o frete grátis se aplicar e o destino tiver preço, o método é exibido com preço 0.
Courier to the door: o plugin pede à ShipLogic o serviço mais barato do seu endereço de remetente até o endereço do cliente. Antes, a rua, a cidade, a província e o CEP do cliente devem estar preenchidos. Até lá, o preço da tabela é exibido.
TCG locker: a tarifa em tempo real é o serviço mais barato de porta a locker até o locker mais próximo da cidade do cliente. Ela não é recalculada para o locker que o cliente escolher.
O pedido inteiro é cotado como uma única encomenda: peso total, maior comprimento e largura e as alturas empilhadas. Produtos sem dimensões contam como cubos de 10 cm. O valor em rands é convertido para a moeda da sua loja. O nível de serviço, por exemplo ECO, é salvo na linha de entrega do pedido.
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 dos dois se aplicar, o método fica oculto.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin 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: eles são escolhidos em uma lista. As tarifas em tempo real e os lockers são apenas para a África do Sul. Os demais países usam a tabela de preços. É exibida apenas uma tarifa por instância de zona (o nível de serviço mais barato), sem escolha de níveis de serviço, seguro ou extras na finalização de compra.
Pontos de retirada
Quando o cliente escolhe uma tarifa TCG locker na finalização de compra clássica ou de blocos, um seletor de locker aparece logo abaixo. Ele lista os lockers que a ShipLogic retorna para a cidade do endereço de entrega, do mais próximo ao mais distante. O cliente pode digitar outra cidade, bairro ou CEP e clicar em Search. É preciso escolher um locker antes de o pedido poder ser feito.
O locker é verificado novamente no servidor, contra a lista da ShipLogic. O nome e o fornecedor vêm da ShipLogic, nunca do navegador. A escolha se mantém durante as atualizações da finalização de compra e é redefinida quando o endereço muda.
Se a ShipLogic não puder ser acessada, o seletor informa que os lockers não puderam ser carregados, e o pedido pode ser feito sem locker. Nesse caso, o pedido é sinalizado: "Not chosen — ShipLogic was unavailable at checkout. Agree the locker with the customer." (Não escolhido: a ShipLogic estava indisponível na finalização de compra. Combine o locker com o cliente.)
Pedidos
O locker escolhido (nome, ID e fornecedor) é salvo no pedido. Ele aparece na tela de pedido do administrador, nas páginas "Obrigado" e "Minha conta" e nos e-mails de pedido (HTML e texto simples). O e-mail do administrador também mostra o ID do locker.
Na tela de pedido do administrador, os pedidos deste método têm um campo The Courier Guy tracking reference. Digite o código do seu portal da The Courier Guy e clique em Save. O código é exibido ao cliente na página do pedido e nos e-mails enviados depois.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera o domínio dele. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a The Courier Guy não é exibida aos clientes na finalização de compra. Os gerentes da loja que estiverem conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente em segundo plano, automaticamente.
Solução de problemas
A The Courier Guy não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ligado e o país está permitido). Confira os limites de peso, o Minimum order amount e as Excluded shipping classes. Verifique se a tabela ou o Fallback cost têm um preço. As tarifas de locker aparecem somente para endereços sul-africanos.
Os clientes não veem a lista de lockers: os lockers exigem a chave de API, um método de zona com Delivery type "TCG locker" 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: confira 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 para ZAR. Para a entrega em casa, a rua, a cidade, a província e o CEP do cliente precisam estar preenchidos. Para os lockers, a ShipLogic precisa encontrar um locker perto da cidade do cliente. Ative o Debug log e abra WooCommerce > Status > Logs, origem vfd-the-courier-guy.
A ShipLogic está fora do ar: é exibido o preço da tabela ou o alternativo. Pedidos com locker podem ser feitos sem locker e são sinalizados no pedido.
As tarifas parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as tarifas e os lockers em cache.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém as configurações e apaga apenas as tarifas e os lockers em cache. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, as tarifas e os lockers em cache e o último erro são sempre removidos. As configurações e as tarifas por zona só são removidas se Remove data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Lockers e códigos de rastreamento salvos nos pedidos nunca são removidos, e os pedidos existentes mantêm suas linhas de entrega.
The Courier Guy e ShipLogic são marcas de seus respectivos proprietários. Este plugin não é afiliado nem endossado pela The Courier Guy ou pela ShipLogic.